Common errors

Common errors

Start every investigation with the running binary and the offline doctor:

which -a gormes
gormes version
gormes doctor --offline
gormes config check
gormes gateway status

Symptom	Likely cause	Fix
gormes not found after install.sh	The current shell has not picked up the installer’s published bin directory. Non-root Unix installs use $HOME/.local/bin by default.	Open a new shell, or add export PATH="$HOME/.local/bin:$PATH" to your shell rc.
Termux install reports unknown command /data/data/com.termux/files/usr/bin/gormes for gormes	The installed command is likely the older v0.2.20 Termux binary or another stale gormes earlier on PATH.	Install v0.2.22 or newer from the latest release, then run which -a gormes, gormes version, and gormes doctor --offline to confirm the recovered binary is active.
Command behavior looks stale or matches an older release	Multiple gormes binaries on PATH.	which -a gormes and run the intended path directly, or remove the older copy.
gormes chat -q "..." fails with “provider auth missing”	No API key for the configured provider.	gormes auth add <provider> --api-key ... or run gormes setup provider.
gormes doctor reports provider not reachable	Endpoint, network, or credential mismatch.	gormes config show and verify [hermes].endpoint, then re-run gormes doctor.
Config edits do not take effect	Config file is not where you think it is.	gormes config path and edit the file it reports; GORMES_HOME overrides the default ~/.gormes.
Secrets do not load	.env is missing or in the wrong place.	gormes config env-path and put provider tokens at the reported path.
Telegram bot stays silent	Gateway not running, or token/chat-id misconfigured.	gormes gateway status; verify GORMES_TELEGRAM_TOKEN and the allowed chat ids in config.
Browser tools fail	Chrome/Chromium not started with remote debugging.	Launch Chrome with --remote-debugging-port=9222 --user-data-dir=$HOME/.gormes/chrome-debug, then export BROWSER_CDP_URL=http://127.0.0.1:9222.
gormes crashes on launch	Panic before TUI start.	Look in ~/.gormes/ for the most recent crash-<unix>.log; the stderr message also names the crash file.
TUI session resumes with stale state	bbolt session map at ~/.gormes/sessions.db.	gormes --resume new starts a fresh default session.
gormes doctor warns about GitHub auth	gh not authenticated and no token in env.	gh auth login, or export GITHUB_TOKEN=....

Termux v0.2.22 recovery answer template

When summarizing the recovered Termux installer issue, use this wording:

• Public latest: v0.2.22 carries forward the Termux executable-argument recovery.
• Historical symptom: unknown command /data/data/com.termux/files/usr/bin/gormes for gormes on affected v0.2.20 installs.
• Operator action: reinstall from the latest release, then run which -a gormes, gormes version, and gormes doctor --offline.
• If the symptom persists after reinstall, check for a stale v0.2.20 binary earlier on PATH before filing a new installer bug.

Other useful answers

Do I need Hermes running? No. gormes --offline boots the native TUI and keeps typed messages local. No Hermes process, Python, Node, or Docker required for the offline path.

Where does memory live? Goncho-backed local memory under ~/.gormes/ (see gormes goncho doctor --json for the active configuration).

How do I reset a session? gormes --resume new.