Hermes Agent troubleshooting

Diagnose Hermes Agent by component

Work top to bottom. Each row tells you what to suspect and which check settles it.

Capture version, environment, and exact error

Do this before changing anything. Without it you cannot tell whether a change helped.

Record four things every time: the exact error string, whether it reproduces, what changed immediately before it started, and your Hermes Agent version.

Installation failures

Documented symptoms and their causes:

• hermes: command not found — the shell has not reloaded PATH. Open a new terminal or re-source your shell profile. This is not a failed install.
• Python version too old — Python 3.11 or newer is required. Check with python3 --version.
• node: command not found even though Node is installed — a login shell that does not source the file where your version manager registers itself. The documented fix is to list the relevant files under terminal.shell_init_files in config.yaml.
• uv: command not found — the Python package manager is not installed; install it, then re-run the installer.
• Permission denied during install — do not reach for sudo; re-run the standard per-user installer.

If the installer itself will not complete, or you need to change method entirely, go to reinstall or repair installation.

Provider and authentication failures

• API key not working — re-run hermes model, or set the key explicitly with hermes config set.
• Model not found or not available — the identifier does not match what the provider serves; list what is available with hermes model.
• 429 rate limiting — wait, switch model or provider, or raise the plan limit.
• Context length exceeded — compress the session, start a fresh one, or set context_length explicitly for endpoints that misreport it.
• Error 400 on the first run — usually a model-name mismatch or a key without access to that model. Verify the resolved configuration, then re-run the provider picker.
• Only one provider appears under /model — you can only switch between providers already configured; exit and run hermes model from the terminal to add one.

The setup steps behind each of these belong to provider authentication checks.

Configuration failures

Resolve in this order:

1. hermes config get <key> — what value actually won?
2. Which source set it: a command-line flag, config.yaml, .env, or a default?
3. hermes config check — is anything missing after an upgrade?
4. hermes config migrate — add newly introduced options interactively.

If a file edit did not take effect, the usual cause is precedence rather than syntax. The full precedence table and the safe-editing procedure are in validate configuration.

Tool, sandbox, and terminal failures

• A tool is not available at all — it is not in an enabled toolset. Check with hermes tools.
• Commands are blocked — approval mode or a deny rule refused them. Read the refusal, and remember that the hardline blocklist applies regardless of mode.
• The Docker backend will not connect — the daemon is not running or your user lacks permission. Confirm with docker info.
• sudo does not work through a messaging gateway — the gateway has no interactive terminal, so a password prompt cannot be answered.
• MCP server not connecting — the binary or endpoint is unreachable, or the runtime is missing. Verify the server runs standalone first.
• MCP tools missing after connecting — discovery failed or your include/exclude filters removed them; reload with /reload-mcp.

Dashboard and gateway failures

• Gateway will not start — missing optional dependencies, a port conflict, or a misconfigured token. Check the port and read ~/.hermes/logs/gateway.log.
• Bot not responding — confirm the gateway is running with hermes gateway status, then confirm the sender is authorised. With no allowlist configured, every user is denied by design.
• Messages not delivering — expired platform token, network path, or webhook misconfiguration.
• Gateway keeps dropping under WSL2 — documented as systemd unreliability in WSL; run it in the foreground or under a terminal multiplexer instead.
• macOS: Node.js or ffmpeg not found when run by the gateway — the service captured a minimal PATH; re-run the gateway install so it re-snapshots the environment.

Windows and Docker failures

Platform-specific paths, kept short because their owners carry the detail:

• Windows — WinError 193 means a Node tool needs its .cmd shim; encoding artefacts point at the console host; a stalled browser tool usually means Chromium provisioning failed.
• Docker — configuration that resets between runs means the volume is not mounted at /opt/data; a crashing browser tool means shared memory or container RAM is too low; corrupted state usually means two gateways shared one data directory.
• Docker updates — hermes update is not supported in a container; pull a new image and recreate the container.

Verify recovery

A fix is not confirmed until all four pass:

• hermes doctor completes without the original error.
• The exact failing action now succeeds — the same command, not a simpler one.
• A tool-using task shows real tool activity.
• The result survives a restart, and a fresh session behaves the same way.

Create a reproducible issue report

If it still fails, make it easy for someone else to reproduce:

1. Hermes Agent version (hermes --version) and how you installed it.
2. Operating system and version; note WSL2 or a container if relevant.
3. Python version (python3 --version).
4. The exact error string, copied rather than paraphrased.
5. Minimal steps to reproduce, starting from a fresh session.
6. What you already tried and what changed.
7. Relevant log excerpts from ~/.hermes/logs/, with secrets removed.

hermes dump assembles most of that for you; hermes debug packages logs and system information. Review both for sensitive values before posting, then file the report on the project's issue tracker.