Skip to content
China Explained

Troubleshooting

Troubleshooting

Section titled “Troubleshooting”

The most important Hermes debugging rule is: do not change too many things at once. Hermes spans Python environment, model provider, prompt, tools, filesystem, gateway, and long-term state. If you reinstall, switch models, rewrite the prompt, and toggle tools all at once, you will not know what changed the behavior.

Reproduce the smallest failure

Section titled “Reproduce the smallest failure”

Start with the smallest commands:

Terminal window
command -v hermes
hermes --help
python -m pip show hermes-agent

If the command layer works, move into a low-risk directory and run a tiny session. Do not debug through the original large task first.

Locate the layer

Section titled “Locate the layer”
LayerTypical symptomFirst action
Installcommand not found, import errorCheck PATH, Python version, package location.
Providerauth failure, missing model, rate limitRun hermes model again; confirm key, account, model name.
Model qualitymessy output, poor tool callsTest a smaller task; compare the same prompt across models.
Prompt/contextproject rules ignored, old assumptions returnCheck context files, memory, skills.
Toolswrong path, command failure, API errorRun the tool or command outside the agent.
File statewrong files changed, strange diffCheck pwd, git status --short, Git diff.
Gatewayno messages, mixed sessionsCheck token, allowlist, session routing, gateway logs.
Cron/automationbackground task misbehaves silentlyCheck owner, logs, schedule, config refresh, shutdown path.

Most debugging moves left to right. Later layers have more variables.

If install works but Hermes will not answer

Section titled “If install works but Hermes will not answer”

The usual cause is provider configuration:

  1. Run hermes model again.
  2. Confirm the provider account works.
  3. Confirm the model name still exists.
  4. Check whether API key or OAuth expired.
  5. If using an OpenAI-compatible endpoint, send a minimal request outside Hermes.

Do not begin by rewriting a complex prompt. If the model path is broken, prompt quality is irrelevant.

If old assumptions keep returning

Section titled “If old assumptions keep returning”

Find the source:

  • Only this conversation: session state.
  • Every new conversation: memory or global context.
  • Only this project: AGENTS.md, .hermes.md, CLAUDE.md, or similar files.
  • Only one task type: the relevant skill.

Deleting the bad source is more reliable than negating it in every prompt.

If tool calls fail

Section titled “If tool calls fail”

Look at the real error, not only the final answer:

Terminal window
pwd
git status --short
which node
which python

If Hermes wants to run a command, try a read-only or dry-run version in the terminal. Path, permission, dependency, and network issues should usually reproduce outside the agent.

If gateway or cron breaks

Section titled “If gateway or cron breaks”

Remote and background issues require one extra question: which process is actually running?

  • Did it load the latest config?
  • Are token and allowlist correct?
  • Which session did the message enter?
  • Is the long-running process still on an old version?
  • Where are logs, and are secrets redacted?
  • How do you stop and restart safely?

Many gateway problems look like “the agent ignores me,” but are really bot token, platform permission, session routing, or service process issues.

Save this debugging note

Section titled “Save this debugging note”
Hermes version:
Install method:
Python version:
OS and shell:
Provider:
Model:
Command or prompt:
Working directory:
Expected result:
Actual result:
Relevant log or error:

It is short enough to fill in, and enough for someone else to identify the layer.

Section titled “Related pages”

References

Section titled “References”