Troubleshooting

Problems grouped by what you see: an error message, a nan, a number that looks wrong, or a message that only looks like an error. For known defects, see Known issues.

Errors and warnings that start with `GRANDlib:`

Public functions check their input. A message that starts with GRANDlib: names the function and the argument, what was expected and what was given:

ValueError: GRANDlib: Geodetic: 'latitude' must be between -90 and 90 degrees, got 200.0
TypeError: GRANDlib: TRun.run_number: must be an integer, got 1.7
FileNotFoundError: GRANDlib: EventList: no such file or directory: /data/run_1

Error and warning messages below lists the common ones, with what to do.

They are the standard exceptions (TypeError for the wrong kind of value, ValueError for a value out of range or of the wrong shape, FileNotFoundError for a missing file), so except works as usual.

A value that is suspicious but usable, such as a tree field outside its physical range, gives a GRANDlibWarning and is used as given. To find where warnings come from, turn them into errors:

import warnings
from grand.basis.validate import GRANDlibWarning
warnings.simplefilter("error", GRANDlibWarning)

Opening a tree on a file that does not exist is not an error: it creates the file, because that is how trees are written. A mistyped file name therefore gives an empty tree.

Nothing raised, but the answer is `nan`

An elevation lookup returned ``nan``. There is no SRTM tile for that one-degree square. Tiles are not in version control and a fresh checkout has none:

from grand.geo import topography
from grand.geo.coordinates import Geodetic

site = Geodetic(latitude=40.98, longitude=93.95, height=0.0)
topography.update_data(site, radius=50e3)

The nan propagates through elevation(..., reference='sea'), which subtracts the undulation from it. Check for ``nan`` after every elevation lookup.

The numbers are wrong but nothing failed 

The most common causes (arms read as field components, hertz for megahertz, degrees for radians, mixed-up frames) are in the cheat sheet’s table. The others:

Changing ``vga_gain`` changes nothing. It is ignored. See The VGA gain setting has no effect.

Two noise levels disagree by a factor of two. If either was simulated before 7 September 2026, see Voltages simulated before 7 September 2026. Since then the three antenna models agree to about 10%.

``leff_theta`` is ``None``. The loaded tables hold the real/imaginary form in leff_theta_reim; the polar attributes leff_theta, leff_phi, phase_theta and phase_phi exist and are never populated.

Error and warning messages 

The messages GRANDlib gives most often, as they appear. Search this page for a few words of the message you got; … stands for the part that changes.

Files and folders

no such file or directory: …: The path does not exist. A relative path is relative to the directory Python runs in; in a notebook, that is notebooks/.
no ROOT files (*.root) in …: The folder exists but holds no ROOT file: check that it is the folder sim2root.py wrote, not its parent.
no GRAND event files recognized in …; files must be named <type>_<events>_L<level>_<serial>.root: The folder holds ROOT files whose names do not follow GRAND’s convention, such as efield_1-2_L0_0000.root, so their trees cannot be found. Rename the files, or open each one with its tree class (TEfield, …).
… holds no efield file / … holds no run file / … holds no shower file: Efield2Voltage needs the whole folder sim2root.py wrote, with its efield_*, run_* and shower_* files; a single e-field file is not enough.
… holds efield files at levels 0, 1: reading the highest (warning): The folder holds several analysis levels. Choose one with efield_level=0 in Python or --level 0 on the command line.
… holds an efield file at level … but no run file at that level: The run file carries the sampling interval, so it must exist at the level of the e-field file. Convert the simulation again, or choose another level.
cannot tell which run and shower trees belong to …: a GRAND filename carries its analysis level as '_L0_' or '_L1_': The file readers of grand.dataio.root_files find a file’s run and shower trees by its name, which must carry _L0_ or _L1_. Rename the file, or read its trees directly (The file readers depend on file names).
DataDirectory: … is named level … but its … tree is level … (warning): The _L0_ or _L1_ in a file name disagrees with the analysis_level stored in its trees; the trees’ level is used. Rename the file to match.
convert_voltage2adc: no voltage_*_L<level>_*.root in …: Run convert_efield2voltage.py on the folder first (Command-line tools).

Writing files

… is being written by another process / … was changed by another process: Two processes tried to write the same ROOT file, for example two batch jobs with the same output name. Only one process may write a file at a time; the other is refused rather than allowed to lose events or corrupt the file. Give each job its own output file, or wait for the first to finish and run the second again.
NotUniqueEvent: An event with (run_number,event_number)=(…) already exists: Two events with the same run and event numbers were written into one tree, most often by running a simulation twice into the same output file. Give each run its own output file, or change event_number.

Reading events

no event … in run … in the input; it holds (event, run) … / no event with event number … and run number …: The numbers are wrong, or swapped: GRANDlib takes the event number first. tree.get_list_of_events() lists the (event, run) pairs a file holds.

Values

'lst' must be 0 to 24 h / 'f_lst' (local sidereal time) must satisfy 0 <= f_lst < 24 hours: The local sidereal time is in hours, not degrees.
'…' = … is outside -6.28319 to 6.28319 rad; is it an angle in degrees? (warning): grand.analysis works in radians; convert with np.radians. The trees and the simulation use degrees.
the peak times span … s, more than a shower front takes to cross any array; are they in ns rather than s? (warning): The reconstruction takes times in seconds; divide nanoseconds by 1e9.
Source direction at zenith … deg, outside the antenna table (…; below the antenna's horizon): its effective length is taken as zero (warning): The shower maximum is below the antenna’s horizon, so the antenna is taken to see nothing from it. This happens for nearly horizontal showers over uneven ground, or when Xmax is wrong in the input.

Installation

data model incomplete: … is missing / data model damaged: … has … bytes

A file of the model data is missing or was not downloaded completely. Run python data/download_data_grand.py (source env/setup.sh does it).

ModuleNotFoundError: No module named 'ROOT'

The environment is not active, or ROOT is not installed. import grand works without ROOT, but reading files, topography and the simulation need it (Topography, the data layer and the simulation need ROOT).

conda activate grand-dev

ImportError for turtle or gull

The C extensions are not built. They compile from source:

source env/setup.sh

Messages that look like errors and are not 

No valid trun TTree in the file ... Creating a new one.: Expected when writing: constructing a tree class on a file that does not yet contain that tree creates it. When reading a file you expected to hold the tree, it means the tree is absent or named differently.
TClass::Init:0: RuntimeWarning: no dictionary for class ... is available: ROOT could not find a dictionary for a class it does not need. Harmless.

Reading files 

``DataDirectory`` returned fewer handles than there are runs. It groups by tree type and analysis level, not by run, so two runs in one folder do not give two handles. Notebook 02 works through this.

A bare attribute gave the wrong level. A bare attribute such as tefield follows the highest level present. Ask for the level explicitly, as tefield_l0.

A reader wants a directory, not a file. Some readers are coupled to directory layout rather than taking a path; see The file readers depend on file names.

Memory grows with every file. Release each tree when done with it: use with TADC(path) as tadc: or call tadc.stop_using() at the end of each iteration (Reading many files: release each tree).

Environment and build 

The installation fails. See Installation and requirements.

A result changed after a ROOT upgrade. Check first that the computation is deterministic: seed every random draw and reproduce the difference twice before attributing it to ROOT.

Still stuck 

Check Known issues, then see Getting help for how to ask on GitHub.