"Your API key was rejected by the provider." But the key works in curl. It works on the provider's website. It works in every other tool. Just not in Hermes. Here are six causes from real GitHub issues.
A user on GitHub issue #14637 verified everything. API key: valid. OpenRouter credits: available. Key in ~/.hermes/.env: correct. Direct curl to OpenRouter: works.
Hermes: AuthenticationError [HTTP 401] User not found.
The key was right. Hermes was sending the wrong one.
Authentication errors are the second most common Hermes runtime failure (after HTTP 400). The error message always blames your API key. In four of the six cases below, the key is fine. The problem is how Hermes resolves, stores, or transmits credentials to the provider.
Here are six causes, sourced from real GitHub issues, with the exact fix for each.
Cause 1: API key drift after switching providers (the silent killer)
GitHub issue #14134: "api_key drift on provider switch. The hermes model picker for API-key providers routes through _model_flow_api_key_provider(). When switching between providers, the old API key can persist."
What happens: You set up OpenRouter. It works. You switch to MiniMax. Hermes stores the MiniMax key but the request pipeline picks up the old OpenRouter key from a different config path. The provider receives a valid key... for a different provider.
The fix: After switching providers, manually verify ~/.hermes/.env:
cat ~/.hermes/.env | grep -i key
Remove any stale keys from previous providers. Then verify the active config:
hermes config show | head -20
Confirm the provider, model, and key all point to the same service.
The auth debugging rule: Always verify three things match: the provider in config, the model ID format for that provider, and the API key for that provider. If any of the three points to a different service, you get 401.
Cause 2: Setup wizard silently skips key replacement
GitHub issue #16394 (P2): "hermes setup silently skips the API-key prompt if any value is already present in ~/.hermes/.env, regardless of whether that value is valid."
What happens: You run hermes setup to reconfigure with a new API key. The wizard shows provider selection, model selection... then skips the key prompt entirely because an old key exists. You think you entered the new key. You didn't. The old (now invalid) key is still in .env.
The fix: Edit the key directly:
hermes config edit or manually edit ~/.hermes/.env
Replace the old key with the new one. Save. Restart the gateway. The wizard's skip behavior was fixed in a later version (#20162), but verify you're on v0.13.0+.
For the broader comparison of agent authentication approaches, our comparison covers how different platforms handle credential management.
Cause 3: Anthropic OAuth sends to wrong endpoint with null auth
GitHub issue #12905: Six distinct bugs in one debugging session. The worst: "Fresh install with provider: anthropic dispatches to https://api.anthropic.com/chat/completions (OpenAI-style path, does not exist on Anthropic) with Authorization: Bearer None."
What happens: You configure the Anthropic provider expecting to use Claude Code credentials via OAuth. Hermes sends the request to an OpenAI-compatible endpoint (which Anthropic doesn't have) with a null Bearer token stringified as "None". Response: 400.
The deeper issue: Anthropic routes third-party OAuth tokens to a separate extra_usage billing pool, not your subscription quota. Even with a valid Max subscription showing 80% remaining, the OAuth path returns "You're out of extra usage."
The fix: Don't use Anthropic OAuth for Hermes. Use a direct API key from console.anthropic.com. Or use Anthropic through OpenRouter (which handles the auth correctly). The OAuth credential reuse from Claude Code is documented as misleading (#12905).
Cause 4: Dual Gemini auth headers (also covered in the 400 post)
GitHub issue #7893: Hermes injects x-goog-api-key AND the OpenAI SDK injects Authorization: Bearer. Google rejects the dual credentials.
The fix: Use a standard Google Cloud API key starting with AIza.... Avoid Vertex AI keys. This overlaps with the Hermes Error 400 troubleshooting guide which covers the same dual-header bug from the 400 error perspective.
Cause 5: Intermittent 401 on valid keys (MiniMax, GLM)
GitHub issue #8283: "The agent intermittently returns HTTP 401 authentication_error: invalid api key randomly despite the API key being valid. The error occurs randomly. This has been reproduced with both MiniMax M2.7 and GLM providers. Reinstalling Hermes three times has not resolved the issue."
What happens: Most requests succeed. Some randomly fail with 401. The key is valid. Reinstalling doesn't help. The issue appears to be provider-side: load balancer state, regional API key propagation delays, or rate limiting that returns 401 instead of 429.
The fix: Configure a fallback provider. Hermes supports fallback chains. When the primary returns 401, the fallback catches it. Or switch to a more reliable provider (OpenRouter aggregates multiple backends and handles retries internally). The intermittent 401 is a known pattern with smaller Chinese API providers.
If debugging API key drift, stale credentials in .env files, OAuth endpoint misrouting, dual auth headers, intermittent provider failures, and setup wizards that skip key prompts sounds like more authentication plumbing than agent building, BetterClaw handles provider authentication at the platform level. Paste one API key. Select a model. The platform handles the rest. No .env files. No OAuth routing. No key drift. Free tier with 1 agent and BYOK. $19/month per agent for Pro.
Cause 6: Ubuntu paste bug in setup wizard (P1)
GitHub issue #15768 (P1): "When running hermes setup on Ubuntu, the CLI prompts for 'Paste your API key:' but the terminal does not accept keyboard input."
What happens: The wizard shows the API key prompt. You paste. Nothing appears. You type. Nothing appears. The cursor just sits there. The wizard appears frozen.
The fix: Skip the wizard and set the key directly in the .env file:
Edit ~/.hermes/.env and add your key manually (e.g., OPENROUTER_API_KEY=sk-or-...). Then run hermes model to configure the provider and model without the broken key prompt.
The diagnostic checklist
Step 1: cat ~/.hermes/.env | grep -i key ... Is the right key present for the right provider?
Step 2: hermes config show | head -20 ... Do provider, model, and key all match?
Step 3: curl -H "Authorization: Bearer YOUR_KEY" https://openrouter.ai/api/v1/models ... Does the key work outside Hermes?
Step 4: Did you recently switch providers? Check for stale keys from the old provider.
Step 5: Are you using Anthropic OAuth? Switch to a direct API key.
The authentication error is never about the key. It's about the path between Hermes and the provider. Key drift. Silent skips. Wrong endpoints. Dual headers. Intermittent provider failures. Broken paste prompts. Six different breaks in a path that should be one line: "send this key to this endpoint."
If you want authentication that works without debugging .env files, OAuth routing, and provider-specific header conflicts, give BetterClaw a try. Free tier with 1 agent and BYOK. $19/month per agent for Pro. Paste one key. Pick a model. The auth is handled.
Frequently Asked Questions
What causes "Auth handler error authenticating" in Hermes Agent?
Six common causes: API key drift after switching providers (#14134), setup wizard silently skipping the key prompt (#16394), Anthropic OAuth routing to wrong endpoint (#12905), dual Gemini authentication headers (#7893), intermittent 401 on valid keys with MiniMax/GLM providers (#8283), or the Ubuntu paste bug in the setup wizard (#15768). In four of six cases, the key is valid but Hermes mishandles it.
How do I verify my Hermes API key is correct?
Three checks: cat ~/.hermes/.env | grep -i key (is the key present?), hermes config show | head -20 (do provider and model match the key?), and curl -H "Authorization: Bearer YOUR_KEY" provider-endpoint/models (does the key work outside Hermes?). If curl works but Hermes doesn't, the issue is in Hermes's key resolution, not your key.
Why does Hermes say "User not found" when my OpenRouter key works?
GitHub issue #14637. The most common cause is API key drift: Hermes is sending a stale key from a previous provider configuration. Check ~/.hermes/.env for multiple key entries. Remove stale keys from old providers. Verify with hermes config show that the active provider matches the key in .env.
Can I use Claude Max subscription with Hermes Agent?
Technically yes via OAuth, but with significant caveats. GitHub issue #12905 documents that Anthropic routes third-party OAuth tokens to a separate billing pool (extra_usage), not your subscription quota. Even with 80% subscription remaining, Hermes gets "out of extra usage." Recommendation: use a direct API key from console.anthropic.com, not OAuth.
Does BetterClaw have the same auth issues?
No. BetterClaw manages provider authentication at the platform level. You paste one API key per provider in the dashboard. The platform handles endpoint routing, header formatting, and credential storage (with auto-purge after 5 minutes for security). No .env files. No OAuth confusion. No key drift between providers. Free tier with 1 agent and BYOK. $19/month per agent for Pro.
