Hermes Agent troubleshooting works fastest when you debug in layers: install, model/provider, tools, terminal backend, then gateways. Most failures look mysterious because two layers were changed at once. Start with the CLI, prove one model answer, then add Docker, Telegram, Discord, cron, or webhooks one at a time.
Quick answer#
If Hermes Agent is not working, run hermes doctor, confirm hermes config path and hermes config env-path, choose a provider with hermes model, run one hermes chat -q smoke test, and only then debug tools or gateways. If you do not want to maintain local/VPS setup, Docker, provider keys, or gateway processes, use FlyHermes instead of self-hosting.
The five-layer checklist#
- Install layer: Does
hermes --versionrun? If not, use install Hermes Agent and reload your shell PATH. - Config layer: Does
hermes config pathpoint to the profile you expected? Doeshermes config env-pathpoint to the file that contains your provider key? - Model layer: Does
hermes modelshow the intended provider, and doeshermes doctorpass provider checks? - Tool layer: Does
hermes tools listshow the needed terminal, web, browser, file, GitHub, or MCP toolset enabled? - Gateway layer: Does
hermes gateway statusshow the platform connected, and does a real Telegram/Discord message reach the agent?
Use that order even if the symptom appears in Telegram, Discord, Docker, or a cron job. Gateways and scheduled jobs cannot work if the local CLI cannot answer.
Install and PATH problems#
If the shell says hermes: command not found, reload the shell profile first:
source ~/.zshrc
# or
source ~/.bashrc
Then verify:
which hermes
hermes --version
hermes doctor
On macOS or launchd services, a reduced PATH can also hide git, ssh, node, npm, or bash from Hermes even when they work in your terminal. Start the failing command with a full PATH or restart the service after fixing the environment.
Provider and API key problems#
Provider failures usually come from one of four causes:
- the wrong profile is active;
- the key is in
.envbut Hermes is reading another profile's.env; - the model name does not belong to the selected provider;
- OAuth providers need
hermes login --provider nousor another provider-specific login.
Run:
hermes config path
hermes config env-path
hermes model
hermes doctor
For provider choice and cost-sensitive setup, compare Nous Portal, OpenRouter setup, and local/offline Hermes.
Tools and MCP problems#
If Hermes answers in chat but refuses to browse, edit files, run shell commands, or call MCP tools, this is usually a tool availability issue rather than a model issue.
- Run
hermes tools listand enable the missing toolset. - Start a new session after changing tools; existing sessions can keep the old tool list.
- For MCP servers, run
hermes mcp list,hermes mcp test NAME, then/reload-mcpor restart the session/gateway if the old tool cache remains.
Use tool-call execution and MCP vs API when deciding whether the workflow needs a native API tool, an MCP server, or a normal shell command.
Docker and terminal backend problems#
Docker has two separate meanings in Hermes: running Hermes in Docker, and using Docker as the terminal backend for safer command execution. If terminal tools fail with Docker startup errors or exit 127, check the Docker terminal backend guide. If the whole container loses memory, skills, or config after restart, use the Hermes Docker install guide and verify the ~/.hermes volume mount.
Gateway problems: Telegram, Discord, Slack, webhooks#
Gateway symptoms often hide a healthy CLI underneath. Debug them after the CLI smoke test passes:
hermes gateway status
hermes gateway setup
hermes gateway restart
Then inspect the platform-specific issue: bot privacy and topic permissions for Telegram, bot token and channel permissions for Discord, webhook URLs for webhooks, and uptime/restart policy for VPS or Docker hosts.
Quick decision table#
- Command not found: reload PATH, verify install, then run
hermes doctor. - Model refuses or errors: check active profile, provider, model name, key, OAuth login, and credits.
- Tools are missing: enable the toolset and start a new session.
- Docker sees the wrong files: fix the Hermes home volume or terminal backend config.
- Gateway is silent: prove CLI answer first, then check gateway status, token, permissions, and logs.
- Cron/webhooks do nothing: verify Hermes is a persistent process on a VPS, Docker, launchd, or another supervisor.
When to stop self-hosting#
Self-hosting gives control, but it also means you own provider keys, Docker, service restarts, gateway auth, backups, and logs. If the reader's real goal is an always-on assistant rather than infrastructure maintenance, route them to FlyHermes. If they need control, continue with self-hosting, VPS hosting, and security hardening.
Memory and context failures#
Recent community support threads included how to fix Hermes memory, Local hindsight memory installation broke Hermes, and auxiliary timeout failures during compaction. If Hermes forgets durable facts, resumes the wrong session, or breaks after a memory plugin install, start with the dedicated Hermes Agent memory troubleshooting checklist. Check profile, session, /compress, provider health, and plugin state before deleting any Hermes files.
Recent update and gateway failure pattern#
Recent Discord support demand included Hermes update command hangs (round 2), no menu in choosing models in telegram. update failed, restart loop, and DiscordAdapter attribute errors after code changes. If the symptom started after an update, use the dedicated Hermes update command hangs checklist before reinstalling. Preserve state, fix reduced PATH, verify package metadata, then restart the gateway process. For infrastructure-heavy setups, compare that work with FlyHermes or the self-hosting guide.