Hermes Agent troubleshooting starts with the first failed step. If the provider rejects the request, fix that route before changing tools or reinstalling Hermes. If the model answers but a bot stays silent, check delivery. If Hermes says "done" but the result is missing, check the artifact itself.
Quick answer#
For "Provider authentication failed", read the provider error in the gateway's local logs, then confirm the host, operating-system account and Hermes profile that made the request. A 401 usually needs credential investigation; a 403 may be access or policy; a 402 may be billing; a 429 may be quota or capacity. The response body and endpoint matter more than the code alone. Run one small request under the owning profile after the repair, then test the original channel.
Do not rotate every key, delete session history or reinstall the agent as a first step. Start with the checks below. For a completed but incorrect task, use the acceptance-test and verification sections later in this guide. If you want someone else to maintain the runtime, compare managed Hermes hosting; hosting does not make provider limits disappear.
Provider authentication failed: find the request that failed#
The gateway can show this deliberately brief message:
Provider authentication failed. Check the configured credentials;
raw provider details are in the gateway logs.
It identifies a failure class, not the credential to replace. Inspect the logs on the machine running the gateway at the time of the failed message. Keep raw logs private. Record the provider, model, endpoint host, HTTP status, provider error code and request ID if supplied. Remove authorization headers, tokens, private prompts and account details before sharing an excerpt.
Check the provider's official status page as well. If an incident has just cleared, one short retry may establish recovery without changing credentials. If the response still explicitly rejects the key, repair that key. Do not interpret every sudden failure as an outage, or every 401 as proof the stored secret was revoked.
Confirm the service account and profile#
Here, "service account" means the operating-system user running Hermes, not a cloud billing account. On a VPS, signing in as a different Linux user can select a different home directory. On a desktop, a background service can retain an older environment than a newly opened terminal. A named profile also has its own configuration and secret files.
Run these on the workload's host, as its owning user. Replace work with the real profile name; omit -p work only when the default profile owns the workload. These commands inspect state rather than restart a service:
whoami
hermes --version
hermes -p work config path
hermes -p work config env-path
hermes -p work config get model
hermes -p work auth list
hermes -p work gateway status
hermes -p work doctor
Review the output locally. Even without a raw key, configuration can reveal a private endpoint or account label. Compare the service's configured profile with these paths; a successful test in your laptop's default profile says nothing about a named profile on a VPS. The profiles guide explains the isolation boundary, and the API-key guide covers credential storage.
Choose the repair from the actual error#
- A static API key explicitly rejected as invalid: check the provider account and endpoint, then replace only the rejected credential through the interactive setup or auth flow in the owning profile.
- An OAuth grant rejected with
invalid_grant,invalid_tokenorrefresh_token_reused: reauthenticate the affected entry. Clearing an exhaustion timer does not revive a revoked grant. - A
403or model-access error: confirm project permissions, subscription entitlement, region and the exact model ID. Buying credit is not proof that access has changed. - A
402: inspect the balance and provider-specific spending limits. A positive account balance can coexist with a per-key limit. - A
429: inspect the reset or retry hint and reduce overlapping work. Do not create a fast retry loop or assume another key increases an account-wide allowance. - A timeout after external work: inspect the external target before rerunning the task. The missing reply does not prove the write failed.
Use the provider-cost and rate-limit guide for billing errors. Use provider fallback recovery when logs show a failed primary followed by a different backup route. A backup reply can hide a still-broken primary; record which route answered.
For an authorized credential repair, open the interactive flow rather than placing the secret in a shell argument. Replace the example profile and provider with the ones you identified:
hermes -p work auth list deepseek
hermes -p work auth add deepseek
Do not paste the new key into a chat, commit it, or publish the auth store. If the input looks blank, follow the hidden API-key input checks; invisible input is not proof that the clipboard failed.
Prove recovery in the place that failed#
After updating the credential, safely reload the owning long-running process when active work can be interrupted. First test a small, read-only reply under the same profile:
hermes -p work chat -q "Reply with exactly: provider ok. Do not use tools."
This request can incur model usage charges. Record its timestamp and confirm the actual provider route from runtime evidence; asking the model to name itself is not a routing check. Then send one harmless message through the original DM, group or topic and verify the reply there. Do not test recovery by repeating a payment, public post or deployment.
If the CLI now works but the bot still fails, continue with gateway troubleshooting. If text works but images or compression fail, inspect that auxiliary task's provider configuration. If both work but the requested output is wrong, use the result-verification checklist below.
These commands and credential states follow the current official CLI reference, profile documentation and credential-pool documentation, checked October 14, 2026. They are a recovery procedure, not a claim that we reproduced a provider outage.
Read-only cron triage before a destructive retry#
For a scheduled task, begin with hermes cron doctor, hermes cron runs --limit 20, and hermes cron incidents in the owning profile. These records answer different questions: current findings, individual attempts, and repeated failure signatures. Silence from the incident notifier is not evidence of recovery because identical failures can be withheld during a cooldown.
Classify the result before acting: blocked_config needs prerequisite repair, delivery_failed needs send-path repair, and unknown needs external-state reconciliation. Read back the exact file, message, deployment, or record before repeating a side effect. Use the cron recovery decision path, then report the verified artifact rather than converting a trigger acknowledgement into a claim that the task finished.
Source: official Hermes scheduled-task documentation.
Installation failed: separate package, runtime and user data#
Before reinstalling, identify the installation that actually launches. On POSIX run command -v hermes; in a new Windows PowerShell window run Get-Command hermes -All. Follow with hermes --version and hermes doctor. A bundled Desktop includes its base runtime; a Hermes-Setup bootstrap or source script builds a source installation. A compiler or npm-build failure is not the same failure as a signed package failing to open.
Keep application ownership and data ownership separate. App Installer updates a sideload MSIX, Store updates its own package, macOS Desktop updates its bundle, and hermes update handles a managed source checkout. Do not run Git or a second installer against package-owned app files. Never delete the Hermes home to repair an application. If a symlinked home is unavailable, restore the intended storage and permissions rather than replacing it with an empty local directory.
Use the platform-specific installation runbook to reach one verified provider response before adding tools. The official install layout and update ownership table, checked October 30, 2026, support these branches. They are source-verified recovery instructions, not a clean-machine install test.
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:
- Artifact: the exact file, URL, message, report, commit, or configured service that must exist.
- Constraints: what must not change, which environment is in scope, and which secrets or production surfaces are off limits.
- Acceptance test: the command, browser action, API read, or real-world check that decides pass or fail.
- Evidence: the output that must be included in the final report, such as test results, screenshot path, live URL, delivery ID, or source links.
- 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.
Tool output appeared, but the reply never finished#
Do not classify an entire turn as failed merely because its final explanation is missing. A directory listing can complete before a follow-up model request stalls; a send or write can also succeed before that stall. Ollama's documented tool loop, checked November 10, 2026, separates tool execution from returning its result to the model.
- Preserve the original tool result, timestamp and request identifier where available.
- Check whether a final model response exists. If it does, investigate client/display delivery rather than rerunning the action.
- If it does not, identify the next request's endpoint, model and actual error or silent stream. Follow the provider-wait diagnosis; a wait label is not proof of exhausted credit.
- Reconcile any external side effect before retrying. Use a non-sensitive read-only tool for the next acceptance check, and require both its result and a correct final answer.
This is an isolation procedure, not a reproduced cause of the November community report. Do not delete session state, rotate every key or buy a plan to repair an unclassified missing summary.
Use the proof ladder#
Choose the highest proof level the task requires:
- Claim: the agent says it is done. This is not verification.
- Artifact exists: a file, config entry, job, or URL is present.
- Local check passes: lint, tests, build, schema validation, or a dry run succeeds.
- Rendered or integrated check passes: the UI is opened, the API is called, or the exact channel is tested.
- 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.
Final verification checklist#
Before accepting “done,” confirm:
- the expected artifact exists in the correct environment;
- the diff contains only intended changes;
- relevant tests and builds passed;
- the real integration or rendered surface was checked;
- production was checked when production was requested;
- screenshots, delivery IDs, URLs, or source links are preserved;
- unverified assumptions are labeled;
- the next session can continue from a factual handoff.
Hermes is most reliable when verification is part of the task, not a favor requested after the agent has already declared success.
Classify a stuck browser before changing the model#
If unrelated public URLs all hang after Chrome or the gateway restarted, test the browser transport before blaming model quality. The Hermes browser automation troubleshooting guide separates stale CDP endpoints and harness daemons from anti-bot challenges, wrong profiles, Docker routing, and page-level JavaScript failures.
Failing session persistence is not a normal completed turn#
If Hermes reports session storage unavailable or session_persistence_failed, stop treating the conversation as safely resumable. Follow the state.db recovery decision tree, preserve the database and sidecars, and verify a persisted turn can be resumed before continuing high-value work.