1. Always Start With hermes doctor
Before you Google an error string or dig through logs, run the built-in health check:
hermes doctor diagnoses most configuration and provider issues — missing keys, a model that's too small, a broken PATH, an out-of-date build — and points you at the fix. Nine times out of ten it saves you the rest of this page. If you're setting Hermes up for the first time and want the full walkthrough, see our guide to installing Hermes Agent first, then come back here when something misbehaves.
2. Symptom → Likely Cause → Fix
Scan for your symptom, apply the fix, and re-run hermes doctor to confirm. Every fix below is covered in more detail in the sections that follow.
| Symptom | Likely cause | Fix |
|---|---|---|
| hermes: command not found | Installer added a PATH entry your current shell hasn't loaded | source ~/.bashrc (or source ~/.zshrc), or open a new terminal |
| Context-window error on first message | Your model is below the 64,000-token minimum | Pick a bigger-context model with hermes model |
| Provider / auth error | Missing or wrong API key | Check keys in ~/.hermes/.env, then reconfigure with hermes model |
| Windows PowerShell blocks the install script | Execution policy / permissions | Run PowerShell as Administrator, or use WSL2 with install.sh |
| Docker config/memory not persisting | No volume mounted for ~/.hermes | Mount a volume: -v ~/.hermes:/root/.hermes |
| Skill writes overwrote your manual edits | Agent-authored skills applied without review | Enable write_approval so skill writes are staged |
| Voice mode not working | Voice extra not installed | uv pip install --python ./venv/bin/python -e ".[voice]" |
| Anything else / stale version | Config drift or out-of-date build | hermes doctor, then hermes update |
3. Why does hermes: command not found happen?
The installer added a PATH entry to your shell's rc file, but your current terminal session was opened before that change, so it hasn't picked it up. Reload the shell — or just open a new terminal:
If hermes still isn't found after reloading, confirm the install actually finished, then run hermes doctor once it's on your PATH.
4. Why does my first message throw a context-window error?
Hermes needs a model with at least a 64,000-token context window. If the model you picked is smaller, the very first message fails because the agent's system prompt and tooling don't fit. Switch to a larger-context model:
5. How do I fix provider and authentication errors?
Provider and auth errors almost always mean a missing, expired, or mistyped API key. Your secrets live in ~/.hermes/.env and your settings in ~/.hermes/config.yaml. Check the key there, then reconfigure the provider cleanly:
6. Windows PowerShell blocks the install script
If PowerShell refuses to run the install script, you have two reliable paths. Either run PowerShell as Administrator and retry, or switch to WSL2 (Ubuntu) and use the Linux install.sh installer — the most battle-tested path for the Python runtime. Full per-platform steps are in the Hermes Agent install guide.
7. My Docker config and memory don't persist
Inside a container, ~/.hermes is wiped every time the container is recreated unless you mount a volume for it. Bind your host's config directory into the container:
With the volume mounted, your keys, settings, skills, and memory survive restarts.
8. Sessions, Updates, Skills, and Voice
- • Lost your work / can't find a chat: list saved sessions with
hermes sessions list, and resume the last one withhermes --continue(orhermes -c). - • Update problems or a stale build: run
hermes updateto pull the latest version, then re-runhermes doctor. - • Agent-authored skills overwriting your manual edits: enable
write_approvalso skill writes are staged for your review instead of applied silently. - • Voice mode not working: install the voice extra —
cd ~/.hermes/hermes-agent && uv pip install --python ./venv/bin/python -e ".[voice]".
Want the bigger picture on how these pieces fit together — memory, skills, sandboxes, and gateways? Our Hermes Agent architecture guide explains what each part does and why it's built that way.
9. Frequently Asked Questions
What does hermes doctor actually check?
It runs Hermes's built-in diagnostics across your configuration and provider setup — the common failure points like a broken PATH, missing API keys, a too-small model, or an out-of-date build — and reports what's wrong so you can fix it. Always try it first.
Why do I get "hermes: command not found" right after installing?
The installer added a PATH entry to your shell rc file, but your open terminal hasn't reloaded it. Run source ~/.bashrc or source ~/.zshrc, or simply open a new terminal window.
Why does Hermes fail on the very first message?
Your chosen model is below the 64,000-token context-window minimum Hermes requires. Run hermes model and pick a provider/model with a larger context window.
Where does Hermes store my API keys and settings?
Secrets live in ~/.hermes/.env and settings in ~/.hermes/config.yaml. If you hit a provider or auth error, verify the key in .env, then reconfigure with hermes model.