Troubleshooting#

Gecko prints gecko: error: ... on standard error and exits with a non-zero status when it can’t produce a report. Problems with individual steps (a screenshot, an unreadable log, email) are printed but don’t stop the run.

Setup errors#

No configuration file found at ~/.config/gecko/gecko.ini. Run: gecko -init: No config exists for this account. Run gecko -init, point GECKO_CONFIG at an existing file, or create /etc/gecko/gecko.ini for the whole machine. See installation.
Configuration file ... has not been initialized: The file is still the blank template. Run gecko -init --config <that file>, or set initialized = true under [System] once you’ve filled it in by hand.
Logs.logs_dir must be set in ... (or Report.report_path, Report.recipient_email, …): A required value is blank. Edit the file or rerun gecko -init.
Report.report_path does not exist: ...: Create the directory, and make sure the operator account can write to it.
Invalid regex in Report.time_pattern: ...: Fix the regular expression. Test it against a real log line with Python’s re module before saving it.
gecko: warning: using legacy config .../triage_package/triage.ini: A config from a pre-0.2 checkout is being used. Move it as the warning says. See upgrading.
you need to include a user and a message in your report: Both -u and -m are required.

During a run#

No X11 displays found: No sockets were found in /tmp/.X11-unix/. This is expected on headless machines. Wayland sessions aren’t supported.
Failed to capture -> :0: [Errno 2] No such file or directory: 'xwd': Install the screenshot tools (see installation).
A screenshot is reported as captured but the PNG is missing or empty: xwd couldn’t connect to the display, usually because the account running Gecko isn’t allowed to. Run Gecko as the user logged into that display, or grant access (for example with xhost or by sharing the XAUTHORITY file).
Error: Permission denied to access the file at ...: The account running Gecko can’t read that log. The rest of the run continues.
Failed to send report: ...: sendmail failed. The report and bundle are still saved locally. Check that /usr/sbin/sendmail exists, that the machine can relay mail, and that the bundle isn’t larger than your mail server’s attachment limit (often 10–25 MB).

Errors missing from the summary#

If a log clearly has recent errors but its section in the text report is empty:

The line doesn’t start with a timestamp matched by time_pattern. Only lines whose timestamp is at the very start are considered.
The timestamp format isn’t accepted. The captured text must be parseable by datetime.fromisoformat. On Python 3.8–3.10 that means fractional seconds of exactly 3 or 6 digits, and no trailing Z.
The timestamp has a UTC offset (+00:00). Gecko compares it with a local time without an offset, prints An unexpected error occurred: can't compare offset-naive and offset-aware datetimes, and skips that file’s summary.
Clock differences. Timestamps are compared with the machine’s local clock. If the logs are in UTC and the machine isn’t, the 24-hour window is shifted by the difference.
The file doesn’t end in .log. Other files are copied but not scanned.

The bundle is very large#

Everything under logs_dir is copied on every run. Point logs_dir at the current night’s logs rather than the whole archive, and check whether the newest file in the science folders is a very large image.

Getting help#

Open an issue at https://github.com/CaltechOpticalObservatories/gecko/issues. Include the output of gecko --version, the full error text, and (with paths and addresses removed if necessary) your configuration file.