# Hermes Agent OAuth login stuck or expired > Diagnose expired or revoked subscription logins, MCP OAuth that never returns, and logins that worked but landed in the wrong Hermes home. Canonical: https://hermeswatcher.com/troubleshoot/oauth-login-expired-or-stuck Section: Troubleshooting ยท Models, providers & cost Last reviewed: Oct 20, 2026 Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources. ## What you see - A 're-authentication required' message in the middle of a session, or a startup warning naming `hermes auth add `. - A subscription login (Nous Portal, Anthropic, Codex, xAI) that worked yesterday and now fails on every request. - An MCP server's browser login that ends on a 'cannot connect' page at `127.0.0.1`, or times out while waiting for the callback. - Logging in from the terminal worked, but the gateway or cron jobs still behave as if you never did. ## Likely causes Hermes refreshes OAuth tokens by itself and retries after a transient 401. A login only becomes dead when the refresh token itself is rejected for good: you changed your password, revoked access, the session expired, or another program using the same login rotated the token first. Hermes then logs one warning naming the fix and takes the credential out of rotation. It doesn't keep retrying on a timer, so the problem stays put until you sign in again. Loopback OAuth flows, used by remote MCP servers and some plugins, redirect your browser to `127.0.0.1` on the machine running the browser. If Hermes is on a server, that listener isn't on your laptop. Finally, tokens are stored under the Hermes home of the user and profile that ran the login, so a gateway running as another user or profile won't see them. ## Check this first - `hermes auth status ` shows the stored login state, and `hermes auth list` shows every credential in the pool. - `hermes status` lists the providers that have credentials, along with gateway state. - For Nous Portal, `hermes portal info` shows whether you're logged in and which provider is actually active. - For a named profile, run the same commands with `-p `. Each profile has its own credential home. - Look at the startup output. A benched credential prints its remaining cooldown, and a dead one prints the re-login command. ## Fix For a dead subscription login, sign in again with `hermes auth add `, for example `hermes auth add nous`, `hermes auth add anthropic --type oauth` or `hermes auth add openai-codex`. For Nous Portal, `hermes portal` or re-selecting it in `hermes model` works too. Any quarantine on the old token clears after a successful login. If a credential is only cooling down after a rate-limit or billing error, `hermes auth reset ` clears the cooldown, and `hermes auth refresh ` proves a grant is still alive and returns it to rotation. For an MCP server on a remote host, run `hermes mcp login ` in a fresh terminal. Don't add the server by editing `config.yaml` inside a running session: the automatic reload only waits 30 seconds, which isn't long enough for a browser login. When the browser lands on the failed `127.0.0.1` page, copy the full address-bar URL and paste it at the Hermes prompt. Alternatively, open a tunnel from your laptop with `ssh -N -L :127.0.0.1: user@host`, using the port Hermes printed. If the server supports it, `hermes mcp login --flow device` skips the callback entirely. - Device-code and paste-the-code logins (Nous Portal, xAI Grok OAuth, Anthropic, and Codex by default) don't need a tunnel at all. - Codex in an always-on setup: if every Codex entry is dead, sign in again in that same home, for example `hermes -p auth add openai-codex`. Don't wait for it to fix itself. ## If it still fails If the login succeeds but the gateway still fails, sign in as the same operating-system user the gateway service runs as, for example `sudo -u hermes -i`, so the tokens land in that user's `~/.hermes`. Restart the gateway afterwards with `hermes gateway restart`. For an MCP login that looks successful but whose tool calls later time out, the provider may not support automatic client registration (Google Drive and Atlassian are the documented examples). Create your own OAuth client in the provider's console, add it to the server's config, and run `hermes mcp login` again. If a tunnel fails with 'Address already in use', something on your laptop is already holding that port. Find it with `lsof -iTCP: -sTCP:LISTEN`, stop it, and reopen the tunnel. ## Related guides - [Hermes Agent rate limits and provider errors](https://hermeswatcher.com/troubleshoot/rate-limits-and-provider-errors.md) - [Hermes Agent MCP tool missing or failing](https://hermeswatcher.com/troubleshoot/mcp-tool-missing-or-failing.md) - [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) - [Hermes Agent profiles: separate agents for separate jobs](https://hermeswatcher.com/learn/profiles-separate-agents.md) ## Related tools - [Models and providers: configure the actual inference route](https://hermeswatcher.com/tools/models.md) - [MCP: connect external tool servers](https://hermeswatcher.com/tools/mcp.md) - [Fallback providers: keep working when your main model fails](https://hermeswatcher.com/tools/fallback-providers.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) ## Sources - [Credential Pools: error recovery (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools) - [Nous Portal: troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal) - [OAuth over SSH and Remote Hosts (official guide)](https://hermes-agent.nousresearch.com/docs/guides/oauth-over-ssh) - [MCP: OAuth-authenticated servers (official docs)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) - [CLI Commands Reference: hermes auth (official docs)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) --- HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt