Hermes

Hermes "Error: Invalid API key" (401)

Last checked

The error

Error: Invalid API key

✗ gemini (invalid API key)

401 {"error": {"message": "Invalid gateway API key (API_SERVER_KEY)", "type": "gateway_auth_error", "code": "gateway_auth_failed"}}

Line 1: a desktop client chatting through the Hermes API server (community hermes-desktop issue #126). Line 2: hermes doctor, API Connectivity section. Line 3: the current API server's 401 body.

A 401 Invalid API key in Hermes can come from three different layers. A desktop app or web UI talking to the Hermes API server must send API_SERVER_KEY, not your OpenAI or OpenRouter key. A provider can reject the model key in ~/.hermes/.env. Or hermes doctor flagged a working Gemini key because old builds probed it the wrong way. Match the message to the layer before regenerating anything.

Why it happens

Hermes has two separate credentials that both surface as 401: the API_SERVER_KEY that protects the Hermes API server on port 8642, and the provider keys Hermes uses to call models. Older gateway builds returned the same generic invalid_api_key code for both, so clients could not tell them apart (issue #39365).

  1. The client is sending the wrong key to the Hermes API server. The community hermes-desktop app (fathah/hermes-desktop, not affiliated with Nous Research) failed every Local-mode chat with Error: Invalid API key because it never sent the Authorization Bearer API_SERVER_KEY header (issue #126 there).
  2. A mismatched or rotated API_SERVER_KEY. The official Hermes Desktop used to mislabel this as an OpenRouter key problem; after issue #39365 the server returns gateway_auth_failed and Desktop asks you to sign in again.
  3. The model provider really rejected the key: a stale key left in ~/.hermes/.env after switching providers, or a key from a different provider.
  4. A hermes doctor false positive on Gemini. Doctor probed Google AI Studio with a Bearer header, which Google answers with 401, so valid keys showed as invalid (issues #21481, #23354, #26623). Fixed on main by June 2026; it now sends x-goog-api-key.

The fix

  1. 1 Read the full message. Invalid gateway API key (API_SERVER_KEY) or gateway_auth_failed is the API server; a provider name or provider error body is the model key; ✗ gemini (invalid API key) is doctor.
  2. 2 For the API server, check API_SERVER_KEY in ~/.hermes/.env, then paste that exact value into the client's connection settings (official Desktop: Settings, Gateways).
  3. 3 Test the API server directly: curl http://localhost:8642/v1/models -H "Authorization: Bearer $API_SERVER_KEY". A 200 means the key is right and the client is at fault.
  4. 4 For a provider 401, compare the key in ~/.hermes/.env with the provider dashboard and run hermes config show to confirm the active provider.
  5. 5 For a doctor-only Gemini failure while chat works, run hermes update. If hermes chat answers, the key is fine.
curl http://localhost:8642/v1/models -H "Authorization: Bearer $API_SERVER_KEY"

Which Hermes Desktop are you using?

Two different apps are called Hermes Desktop. The official one ships inside the NousResearch/hermes-agent repo (apps/desktop) and is launched with hermes desktop or the release installers; it runs its own managed backend or connects to a remote gateway with a token. The other is fathah/hermes-desktop, a popular community GUI that drives Hermes through the API server on 127.0.0.1:8642. Its Local-mode auth bug was marked fixed in May 2026, but later comments report it persisting on non-loopback addresses.

If you use the community app and keep hitting Error: Invalid API key in Local mode, update it first, then confirm the key with the curl test above before changing anything in Hermes.

Still failing?

  • Restart the gateway after editing .env (hermes gateway restart); a running API server keeps the old API_SERVER_KEY.
  • If you use named profiles, each profile resolves its own API_SERVER_KEY and fails closed when it has none.
  • For Anthropic, an invalid x-api-key 401 means Anthropic rejected the key itself; check for a revoked key or an OAuth token pasted where an API key belongs.

Related errors

Full guideHermes Agent Auth Handler Error Authenticating: 5 Real Causes and Step-by-Step FixesEvery error, one pageHermes Agent error index

Hit a different error?

Paste any agent error and get the cause and fix in seconds.

Open the decoder

Frequently asked questions

Is API_SERVER_KEY my OpenAI key?

No. It is any strong random string you choose to protect the Hermes API server. Clients send it as a Bearer token; Hermes then uses your provider keys separately.

hermes doctor says my Gemini key is invalid but chat works. Is it broken?

No. That was a doctor bug: it checked Gemini with OpenAI-style Bearer auth. Update Hermes and the check uses the correct header.

Why did Desktop tell me my OpenRouter key was missing?

Older builds could not distinguish a gateway 401 from a provider 401 (issue #39365). The fix gave the gateway its own error code.

Stop firefighting agent errors

Decoding errors one at a time is the manual version of what BetterClaw automates. Run your agents on a no-code AI agent platform with managed models, retries and config validation built in.

Deploy Your Agent — Start FreeBook a Demo

Free plan available · Pro $49/mo · BYOK · 7-day money-back guarantee