Skip to content
Gormes Docs

Diagnose a broken install

Outcome: A reproducible diagnosis (one failing subsystem, one error string) you can paste into an issue or hand to a maintainer.

Prerequisites: gormes on $PATH.

Steps

Section titled “Steps”

  1. Run doctor with full provider check

    Terminal window
    gormes doctor

    This runs the offline checks and the provider health probe. The first [FAIL] line names the failing subsystem.

  2. Compare with the offline subset

    Terminal window
    gormes doctor --offline

    If offline passes but full doctor fails, the issue is provider credentials, endpoint, or model selection — not the local runtime.

  3. Check first-run configuration state

    Terminal window
    gormes doctor --offline --target terminal --json

    The target block reports readiness, missing setup pieces, and next_command. Run gormes setup --quick --target terminal when the target is not ready.

  4. Inspect the gateway runtime (if you use channels)

    Terminal window
    gormes gateway status
    gormes logs

    gateway status shows the persisted runtime state and per-channel lifecycle errors. logs tails the most recent gateway log entries.

Verify

Section titled “Verify”
Terminal window
gormes doctor --json

Expected: a {build, failed, checks: [...]} JSON document. Every check has a name, a status of PASS, WARN, SKIP, or FAIL, and a summary. The summary of a failing check carries the error reason — copy that into your issue report.

Troubleshooting

Section titled “Troubleshooting”
  • Older Termux v0.2.20 installs report unknown command /data/data/com.termux/files/usr/bin/gormes for gormes → Install v0.2.22 or newer from the latest release, then run gormes version and gormes doctor --offline. If the same path error appears after reinstall, check which -a gormes for a stale binary on PATH.
  • Auth: missing → Run gormes auth add <provider> (see first chat).
  • provider health: [FAIL] → Wrong endpoint, wrong model id, or expired credentials. Try provider setup.
  • Gateway lifecycle=failed → The channel adapter failed to start. The error field in gateway status names the cause (token conflict, missing allowlist, etc.).
  • stale_pid in gateway runtime → A previous gateway crashed without clearing state. Run gormes gateway stop or remove the pid file under ~/.gormes.

See also

Section titled “See also”