Guide

Hermes Agent Errors Cheat Sheet

Q: Why is my Hermes Agent bot not responding?

Usually the gateway is not running (hermes gateway status), the account is not paired yet (look for a pairing code in the chat), or the model call is failing (hermes logs errors shows the provider error).

Q: How do I approve a Hermes pairing code?

Run hermes pairing approve on the machine running Hermes, then message the bot again. Codes expire after one hour.

Q: What does hermes doctor do?

It checks configuration, API keys and dependencies and reports problems. --fix attempts automatic repairs and --live adds short live probes for supported configured tool backends.

Each entry below starts with the exact message Hermes Agent prints, then explains what it means and the fastest fix. Search the page for the words in your error. If yours is not here, the diagnostics section at the end shows how to find out more.

Start Here: Three Diagnostic Commands

hermes doctor              # checks config, keys and dependencies (--fix to repair)
hermes gateway status      # is the gateway running, and under what?
hermes logs errors -n 100  # the last 100 error lines

hermes logs gateway -f follows the gateway log live while you reproduce a problem. hermes doctor --live also runs short live probes against the supported tool backends you have configured.

Setup and Model Errors

“No inference provider is configured”

Hermes has no model to talk to yet. Run hermes model, pick a provider and a model, and paste the key when asked. A fresh install also offers this during hermes setup.

“No API key found for provider …”

The provider is selected, but its key is not in ~/.hermes/.env (or the active profile's .env). Re-run hermes model to enter it, or add the provider's key variable to .env and run hermes gateway restart. A common trap is editing the default profile's .env while the bot runs under a named profile.

HTTP 401 / invalid API key

The provider rejected the key. Copy it again with no stray spaces, confirm it has not been revoked, and confirm it belongs to the provider you selected. An OpenRouter key does not work against OpenAI directly. For OAuth logins, Hermes tries a token refresh first and only fails if that does not work. If it still fails, sign in again.

HTTP 402 / insufficient credits or payment required

The provider account is out of credit. Top it up, or switch to a model you can afford with hermes model. Image and vision tools can hit this on their own, even while chat still works, if they use a different provider from the main model; there the message reads Insufficient credits or payment required. Please top up your API provider account and try again.

HTTP 429 / rate limited

You are sending requests faster than the provider allows. Free models on shared routers hit this often. Wait and retry, move to a paid tier, or add a backup so Hermes switches automatically when the main model fails:

hermes fallback add     # same picker as hermes model
hermes fallback list

Model not found / unknown model (404)

The model ID does not exist on the provider you selected, or the provider retired it. Model IDs are provider-specific: a router such as OpenRouter uses a vendor prefix (anthropic/claude-…), while other providers use their own naming. Pick from the list in hermes model rather than typing the ID.

“Context too large (~N tokens) — compressing”

Not an error. The conversation reached Hermes's compression threshold, so it is summarising older turns to keep the context within budget. Long, tool-heavy sessions trigger it more often; starting a fresh session with /new resets it.

Messaging and Pairing Errors

“Hi! I don't recognize you yet, so I can't reply until the person running this bot approves you.”

This is Hermes's pairing step, not a fault. The message includes a pairing code that is valid for one hour. On the machine running Hermes:

hermes pairing approve telegram <code>
hermes pairing list        # pending and approved users

Then send your message to the bot again; it does not replay the one that triggered the code. Use the platform name you are on (discord, slack, whatsapp, and so on) instead of telegram.

“Too many pairing requests right now.”

Hermes could not issue a new code: the platform already has three pending requests, or it is locked out for an hour after five failed approvals. (Separately, each sender can request a code only once per ten minutes; repeat messages inside that window are ignored.) On the Hermes machine, check hermes pairing list and approve or clear the pending requests (hermes pairing clear-pending), then message the bot once.

Approved, but the bot still ignores you (Docker)

If you ran docker exec <container> hermes pairing approve … as root, the approval file ends up owned by root, and the gateway's hermes user cannot read it. The log shows Pairing file … exists but is not readable. Re-run the command as the right user with docker exec -u hermes <container> hermes pairing approve … and change the existing file's owner back to hermes, or restart the container so its entrypoint fixes the ownership.

Telegram: “Conflict: terminated by other getUpdates request”

Two processes are polling the same bot token. Usually that is a second Hermes gateway (an old terminal, a duplicate service, or a container and a host install), or the same token used by another bot program. Find and stop the extra one:

hermes gateway status
hermes gateway stop --all      # then start exactly one

Separate profiles each need their own bot token. That is why hermes profile create <name> --clone leaves bot tokens behind.

Gateway and Dashboard Errors

“Another gateway instance is already running (PID …)”

One host gateway normally serves every profile, so a second start attaches to the running gateway instead of launching another. This log line (shown to you as A gateway already owns this host) means it found a running gateway it could not attach to. Use that gateway, stop it with hermes gateway stop, or restart it with hermes gateway restart. For an unsupervised gateway started by hand, hermes gateway run --replace replaces it in one step. See how to stop the Hermes gateway.

The bot goes offline when you close the terminal

hermes gateway run lives only as long as its terminal. Install it as a background service. On Linux, install also turns on systemd linger so the service survives logout, and warns you if it cannot:

hermes gateway install --start-now --start-on-login

“Refusing to bind dashboard to … but no auth providers are registered”

You asked hermes dashboard to listen on a non-local address without any login configured, so Hermes refused rather than expose your agent. Set dashboard.basic_auth.username and a password_hash in config.yaml, run hermes dashboard register for Nous Portal sign-in, or keep it local and reach it over an SSH tunnel. The same error appears on a local bind when an external dashboard.public_url is set; for local-only use, remove it and unset HERMES_DASHBOARD_PUBLIC_URL. Details are in Hermes Agent Gateway Token Setup.

`hermes: command not found` after installing

The installer links the hermes command into ~/.local/bin, and that directory is not on your PATH in the current shell. Open a new terminal, or add export PATH="$HOME/.local/bin:$PATH" to your shell profile.

Still Stuck?

Run hermes doctor --fix. It repairs many config and dependency problems by itself.
Check that you are on the right profile: hermes profile list shows which one is active.
Search the upstream issue tracker for your exact error text: github.com/NousResearch/hermes-agent/issues.

On OpenClaw Launch

Managed Hermes bots on OpenClaw Launch avoid most of this list. The model and key are set when you deploy, there is exactly one supervised gateway per bot, and pairing codes are approved from the dashboard instead of a terminal. The dashboard also shows logs, and has Restart for when something does go wrong.

On OpenClaw

OpenClaw's errors are different: its gateway uses tokens and device pairing, which produce messages like pairing required and gateway closed (1008). They have a cheat sheet of their own — see OpenClaw Errors Cheat Sheet.

Frequently Asked Questions

Why is my Hermes Agent bot not responding?

The three usual causes are: the gateway is not running (hermes gateway status), your account is not paired yet (look for a pairing code in the chat), or the model call is failing (hermes logs errors shows the provider error).

How do I approve a Hermes pairing code?

Run hermes pairing approve <platform> <code> on the machine running Hermes, then message the bot again. Codes expire after one hour.

What does hermes doctor do?

It checks your configuration, API keys and dependencies and reports problems. --fix attempts automatic repairs, and --live adds short live probes for the supported tool backends you have configured.

Are OpenClaw errors the same as Hermes errors?

No. The frameworks have different gateways and pairing models, so the messages and fixes differ. The OpenClaw cheat sheet is linked above.

Related Guides

Stop, Start and Restart the Hermes Gateway
Hermes Agent + Telegram — setup and pairing in detail
Best Models for Hermes Agent — avoid the rate-limit treadmill
OpenClaw Errors Cheat Sheet — the OpenClaw equivalent