When should I stop retrying?
Stop when the next retry could mutate migration state, expose secrets, broaden file access, or run unattended automation without a backup.
Symptoms, causes, next checks
Hermes Agent troubleshooting
Troubleshooting should start with the environment, command, backend, provider, and verification date. Most fixes become clearer once you know whether the failure is install, execution, provider, migration, or integration related.
Agent Guide is an independent editorial resource. It is not affiliated with, endorsed by, or sponsored by Nous Research, Hermes Agent, or Hermes/Hermes brand owners. Product names and marks belong to their respective owners.
Intent
hermes-agent-troubleshooting-overview
Sources
9
Schema
2
Links
8
Fast triage table
| Symptom | Likely area | Next check |
|---|---|---|
hermes command missing | Install/PATH | Open a new shell and re-check installer output. |
| Native Windows shell errors | Windows support path | Compare WSL2 and native Windows behavior. |
| Docker cannot see files | Volume mount or working directory | Inspect mounted paths and Docker guide. |
| Provider auth fails | API key/provider config | Check provider name, base URL, key source, and env forwarding. |
| Migration conflict | Existing Hermes state | Run dry-run and inspect conflict list before applying. |
| Skill behaves unexpectedly | Skill instructions or scripts | Audit skill files and tool surface. |
Evidence to capture
- Operating system and shell.
- Hermes version or docs date.
- Exact command and sanitized output.
- Execution backend: local, Docker, SSH, or remote sandbox.
- Provider path and whether the failure happens before or after auth.
- Whether secrets, files, or messaging channels were connected.
Stop conditions
- Stop retrying if the command touches migration state and you do not have a backup.
- Stop sharing logs until secrets are scrubbed.
- Stop adding skills or MCP servers until the base install works.
Triage order
- Confirm the exact route: install, provider, Docker, Windows, migration, skill, MCP, or gateway.
- Capture the command, shell, OS, backend, and sanitized output.
- Check official docs and current GitHub issues before applying invasive fixes.
- Stop and back up if the next command touches migration state, data directories, or credentials.
- Record the final fix so the issue can become a leaf guide if it repeats.
When to create a new troubleshooting page
| Pattern | Publish as page? | Reason |
|---|---|---|
| One-off typo | No | Handle inside the parent install guide. |
| Repeated Windows PATH or Git Bash issue | Yes | Search demand and fix pattern are specific. |
| Docker volume or port exposure issue | Yes | Risk and commands are different from generic Docker setup. |
| Provider auth confusion | Maybe | Publish when there are multiple provider-specific fixes. |
| Security-sensitive issue | Yes | Operators need a dated, careful, source-backed fix. |
Agent Guide judgment
Most Hermes Agent troubleshooting gets worse when operators keep retrying without classifying the failure. First decide whether the issue is install, shell, Docker, provider, migration, skill, MCP, gateway, or workflow design.
The best fix is often to stop: stop retrying migration without backup, stop sharing logs before scrubbing secrets, stop adding skills before the base install works, and stop scheduling workflows before one manual run is stable.
Diagnostic packet
- Operating system, shell, install path, and Hermes version or docs date.
- Exact command and sanitized output.
- Execution backend: local, Docker, SSH, VPS, or sandbox.
- Provider route, model name, and whether auth succeeded.
- Whether files, secrets, messaging gateways, MCP servers, or migration state were connected.
FAQ-backed first checks
| Symptom | First check | Do not do yet |
|---|---|---|
hermes command not found | Reload shell, run which hermes, inspect ~/.local/bin/hermes. | Reinstall blindly. |
| API key not working | Check provider match, config, .env, and hermes model. | Paste real keys into public logs. |
| Model not found | Verify exact provider model identifier and context length. | Assume the agent is broken. |
| Docker backend not connecting | Run docker info and docker run hello-world. | Change Hermes config before Docker is healthy. |
| Gateway bot silent | Check hermes gateway status, logs, token, and allowlist. | Open the gateway to all users. |
| WSL gateway unreliable | Use foreground/tmux/nohup pattern or verify systemd. | Treat WSL like a normal managed Linux service. |
Escalation rule
A troubleshooting item deserves its own page only when it has a repeatable diagnostic packet, a specific environment boundary, and a fix path that differs from the parent guide. Otherwise, fold it back into the canonical install, provider, Docker, security, or workflow page.
Official sources reviewed
| Source | Used for | Last checked | Confidence |
|---|---|---|---|
| Hermes Agent installation guide | Install commands, prerequisites, Windows/native installer details, and post-install checks. | 2026-06-05 | high |
| Hermes Agent Docker guide | Docker run modes, mounted data directory, gateway operation, ports, and production cautions. | 2026-06-05 | high |
| Hermes Agent configuration guide | Provider, model, backend, and environment configuration patterns. | 2026-06-05 | high |
| Migrate from OpenClaw | OpenClaw migration command flow, dry-run posture, and backup/rollback framing. | 2026-06-05 | high |
| NousResearch/hermes-agent on GitHub | Repository discovery, release/source inspection, issues, and contribution context. | 2026-06-05 | high |
| Hermes Agent security guide | Approval modes, gateway authorization, Docker terminal backend hardening, and credential cautions. | 2026-06-05 | high |
| Hermes Agent FAQ and troubleshooting | Command-not-found, provider, Docker, gateway, messaging, WSL, macOS PATH, and local model troubleshooting. | 2026-06-05 | high |
| Public Hermes Agent Docker issue reports | Publicly reported Docker and file-ownership friction patterns. | 2026-06-05 | medium |
| Public Hermes Agent cron issue reports | Publicly reported cron friction patterns; not treated as official product status. | 2026-06-05 | medium |
Known caveats: This hub captures fix patterns, not guaranteed diagnoses. Re-check official docs and current issues before applying invasive changes.
FAQ
Operator checklist
Get the Agent Guide launch checklist
Receive the smoke-test order for install path, sandbox boundary, provider setup, source review, and production checks.