Hermes "Provider authentication failed. Check the configured credentials; raw provider details are in the gateway logs."

Why it happens

The gateway matches the provider's error against an auth pattern (401, invalid API key, "provider authentication failed") and replaces it with this fixed chat message. The real reason is only in the log.

1. The key for the active provider is missing, wrong, or left over from a previous provider in ~/.hermes/.env, or the provider named in config.yaml does not match the key you set.
2. An OAuth subscription login has expired. Codex logins that went stale used to stay broken until you re-authenticated (issue #6651, closed); Hermes now keeps Codex auth in its own auth.json, so a fresh login through hermes auth add openai-codex clears it.
3. On v0.21.3 and earlier a quota 429 could be labelled as an auth failure because the auth pattern was checked first (issue #89401). Fixed in v0.21.4 by PR #115799: quota errors now say they are quota errors and give the reset time.
4. The primary provider was unreachable while Hermes refreshed its credentials, and that network failure surfaced as this auth message without consulting fallback_providers (issue #120608, still open).
5. The key is exported in your shell profile but the gateway runs as a background service and never sees it. Hermes reads ~/.hermes/.env, and that file wins over stale shell exports.

The fix

1. 1 Find the real error. Run hermes logs gateway --level WARNING --since 1h, or grep -iE '401|403|429|quota|credential|auth' ~/.hermes/logs/gateway.log.
2. 2 If the log shows 401, 403 or an invalid key: open ~/.hermes/.env, correct the key for the provider set in config.yaml, and delete leftover keys from providers you no longer use.
3. 3 If the log names an OAuth provider (openai-codex, nous, xai-oauth): log in again with hermes auth add <provider>, then check hermes auth list.
4. 4 If the log shows 429 or quota on v0.21.3 or earlier, your key is fine. Wait for the quota window and run hermes update to get the v0.21.4 fix.
5. 5 Restart the gateway so it rereads .env: hermes gateway restart. Hermes does not hot-reload credentials.
6. 6 Run hermes doctor to confirm the provider check passes.

Where the gateway log lives

Linux, macOS and WSL2: ~/.hermes/logs/gateway.log. On macOS, when the gateway runs under launchd, stderr goes to gateway.error.log in the same folder.

Native Windows: %LOCALAPPDATA%\hermes\logs\gateway.log. Read it with type or Get-Content -Tail 50.

Docker: the official image uses /opt/data as the Hermes home, so the log is /opt/data/logs/gateway.log inside the container, or under your mounted data volume.

If you set HERMES_HOME, the log is in $HERMES_HOME/logs. hermes logs list prints every log file with its size.

Still failing?

• Test the key outside Hermes with a direct curl to the provider; if that also fails, the key or account is the problem, not Hermes.
• Check for a named profile: each profile has its own .env, so the key you edited may belong to a different profile than the gateway is running.
• If the log shows a timeout or connection refused right before the auth line, treat it as an unreachable provider (issue #120608) and check the provider's status page.

Related errors

• Hermes "check gateway logs for diagnostics"
• Hermes "session continuation requires API key"