Hermes Agent Troubleshooting: From “Done” to Verified

Hermes Agent troubleshooting is not only about crashes and API errors. A more expensive failure is an agent that confidently says a task is done even though the requested file, message, deployment, or automation does not work. The fix is to debug both the system and the result: prove the runtime first, define the artifact before the run, steer early when direction drifts, and verify the final outcome outside the chat.

First decide: system failure or result failure?#

A system failure prevents Hermes from doing useful work at all. Examples include hermes missing from PATH, invalid provider credentials, a Docker backend that cannot start, an unavailable tool, or a silent gateway. Follow the layer-by-layer checks later in this guide.

A result failure is different: Hermes ran, used tools, and returned a confident summary, but the requested outcome was not proven. Common examples include:

• code was written but tests were not run;
• a page was built locally but never deployed;
• a cron job was created but never delivered to the target channel;
• a LinkedIn or messaging workflow was proposed but never completed end to end;
• research cited a summary without opening the original source;
• a subagent reported success without returning the file, URL, or test output.

This distinction matters because switching providers may hide the symptom without fixing the workflow. Start with the contract between you and the agent.

Define “done” before the agent starts#

Give Hermes five things at the beginning of a multi-step task:

1. Artifact: the exact file, URL, message, report, commit, or configured service that must exist.
2. Constraints: what must not change, which environment is in scope, and which secrets or production surfaces are off limits.
3. Acceptance test: the command, browser action, API read, or real-world check that decides pass or fail.
4. Evidence: the output that must be included in the final report, such as test results, screenshot path, live URL, delivery ID, or source links.
5. Stop condition: when Hermes should pause instead of guessing—for example, missing credentials, a destructive migration, or an ambiguous production target.

A useful prompt is concrete:

Goal: fix the checkout button on /pricing.
Artifact: the production /pricing page routes to the correct checkout.
Constraints: do not change prices or the FlyHermes app.
Acceptance test: build, open the live page at phone and desktop widths,
click the CTA, and verify the final URL preserves UTMs.
Evidence: commit hash, live URL, DOM no-overflow result, and screenshots.
Stop if: the checkout destination or production project cannot be verified.

This is stronger than “fix the pricing page” because the agent cannot substitute activity for completion. The session handoff checklist uses the same principle when work spans multiple sessions.

Correct drift without throwing away completed work#

Current Hermes sessions support mid-run steering. In the interactive CLI, use:

/steer focus on the authentication module; do not rewrite the billing code

The note arrives after the next tool call and gives the active agent new context without starting a separate user turn. Use it when the current direction is wrong but completed work is still useful. Use /queue <prompt> when the instruction should wait for the next turn instead of changing the current run.

Steering is not a replacement for a clear initial contract. It is a control surface for new evidence, a discovered constraint, or visible drift. If the task itself changed, stop and restate the goal rather than stacking contradictory steering notes.

Inspect changes before trusting the summary#

For code and file work, the final chat message is not the source of truth. Inspect the working tree:

/diff --stat
/diff all
/diff session

/diff session requires checkpoints and shows cumulative changes from the earliest retained checkpoint baseline. For shell-level checks, use the project’s normal git status, git diff, tests, and build commands. A green test is evidence only for the behavior it covers; it does not prove that a deployment completed or a channel received a message.

When checkpoints are enabled, /rollback lists or restores filesystem checkpoints. /snapshot handles Hermes configuration/state snapshots. They solve different problems: checkpoints protect workspace edits during a task, while state snapshots protect Hermes configuration and state. The backup guide covers durable recovery rather than one-session undo.

Use the proof ladder#

Choose the highest proof level the task requires:

1. Claim: the agent says it is done. This is not verification.
2. Artifact exists: a file, config entry, job, or URL is present.
3. Local check passes: lint, tests, build, schema validation, or a dry run succeeds.
4. Rendered or integrated check passes: the UI is opened, the API is called, or the exact channel is tested.
5. Production outcome passes: the live URL contains the change, the scheduled delivery arrives, or the external system records the action.

Stop at level three only when the job is explicitly local. Website publication requires a live rendered check. A gateway fix requires a real message in the exact DM, group, topic, or channel. A scheduled workflow requires one actual run and delivery, not merely a row in the Hermes Web UI.

The five system layers to check#

If Hermes cannot produce even a small verified result, debug from the bottom up.

1. Install and profile#

Run:

hermes --version
hermes config path
hermes config env-path
hermes doctor

Confirm that the process uses the intended profile and Hermes home. Desktop, launchd, Docker, SSH, and cron can see a different PATH or environment from your interactive shell. Use the official install guide for PATH and first-run recovery, or the dedicated Windows Desktop repair guide for GUI bootstrap problems.

2. Provider and model#

Choose one provider with hermes model, then run a tiny chat request before involving tools. Separate authentication and billing errors:

• 401: missing or invalid credential;
• 402: payment, balance, or entitlement problem;
• 403: permission, region, tier, or OAuth entitlement problem;
• 429: rate or capacity limit.

Do not assume a cheaper model means a cheaper completed task. Retries, large context, tool loops, auxiliary calls, and rework all matter. Use the provider cost and rate-limit guide before changing several provider settings at once.

3. Tools and terminal backend#

A model can chat while the required toolset is disabled. Check hermes tools list, enable only the required toolset, and start a new session so the tool schema refreshes. If terminal calls fail before work begins and Docker reports exit 127, switch the terminal backend to local or repair Docker. The Docker troubleshooting guide separates whole-agent containers from the Docker terminal backend.

4. Context and session state#

Use /context and /usage before blaming memory or changing models. Use /compress to reduce a long same-project thread while preserving continuity; use /new when you need a clean session. The memory and context troubleshooting guide separates context bloat, retrieval, compression, and session-reset problems.

5. Gateway, cron, or external destination#

First prove the CLI can answer. Then check the gateway or cron state, provider availability in that process, allowlists, thread/topic routing, and one real delivery. “Connected” is a checkpoint, not proof. The gateway troubleshooting guide covers Telegram and Discord delivery, while the cron jobs guide covers schedules, runtime uptime, delivery targets, and run status.

A copy-paste recovery prompt#

Diagnose this as either a system failure or a result-verification failure.

Expected artifact:
Acceptance test:
Actual result:
Environment/profile:
Last known working state:

First inspect current state. Do not reinstall, rotate secrets, or rewrite files
until you identify the failing layer. If the system works, run the real
acceptance test. Report: root cause, exact changes, commands run, raw pass/fail
evidence, remaining uncertainty, and the next safe action.

When to stop autonomy#

Pause instead of pushing through when the target production project is unclear, credentials are missing, an irreversible action is required, the acceptance test conflicts with the requested artifact, or evidence from the real destination is unavailable. A useful agent knows when continued activity would create risk rather than progress.

For parallel work, require every worker to return a concrete handle and let the parent verify it. The multi-agent workflow guide and subagent delegation guide show how to keep research, implementation, and QA isolated without trusting worker self-reports.