Pricing
Claude Code "OAuth session expired and could not be refreshed": Why It Happens and How to Fix It
Claude Code says "OAuth session expired and could not be refreshed"? What triggers it, fixes from Anthropic's GitHub issues, and how to stay logged in.
9 min read
Error wording, causes and fixes checked Nov 3, 2026 in Anthropic’s Claude Code docs (errors reference, authentication, troubleshooting), the Claude Code changelog (entries through 2.1.317) and four open GitHub issues: #106631, #102811, #97735 and #81937. Every source is listed at the bottom. No affiliate links on this page (how we work).
Failed to authenticate: OAuth session expired and could not be refreshed
Failed to authenticate: OAuth session expired and could not be refreshedOne-line answer: Claude Code tried to renew your saved claude.ai login, Anthropic’s OAuth service rejected the stored refresh token, and Claude Code wiped the saved credentials, so you have to run /login again (or switch automation to a long-lived token).
That’s not me guessing. Anthropic’s errors page says it in one sentence: “Claude Code tried to renew your saved claude.ai login and the OAuth service rejected the stored refresh token, so Claude Code cleared the saved credentials” (errors reference, verified Nov 3, 2026).
The annoying part is that the same failure wears two different outfits. In an interactive session you see:
Login expired · Please run /loginIn claude -p and the Agent SDK you get the scarier version, Failed to authenticate: OAuth session expired and could not be refreshed, with the structured error code authentication_failed (same page). It’s the Seinfeld “Mulva” problem: Claude Code has forgotten who you are, and the only way it remembers is if you tell it again. Retrying doesn’t help either. Anthropic: “Retrying without signing in shows the same message on every request.”
One more thing before the fixes. If you sign in with an API key, a CLAUDE_CODE_OAUTH_TOKEN, or a third-party provider like Bedrock, you “never see this message” (errors reference). This error is only for people logged in with a claude.ai subscription: Pro, Max 5x, Ultra, Team or Enterprise.
When it shows up: interactive vs claude -p vs background subagents
Same root cause, three very different experiences. Here’s where it bites, based on Anthropic’s docs and the open issues as of Nov 3, 2026.
Interactive terminal. You get Login expired · Please run /login. Annoying, but obvious. Since v2.1.210, /status also shows a Login row reading Expired — log in again (errors reference). Anthropic also warns you ahead of time with Your login expires in 3 days · run /login to renew, which “never blocks a request” (authentication docs, verified Nov 3, 2026). Most of us ignore it, which is very human and very costly.
Headless claude -p runs. This is where people get hurt. #81937 (open since Jul 28, 2026) reports claude -p failing with this exact error while interactive claude on the same machine works fine. One commenter says they hit it “at least once every 2-3 days.” Another runs claude -p from an orchestrator and says retries didn’t help: “confirmed across 5 same-day retries on one occurrence, 3 on another,” and an app restart didn’t fix it either. In #102811 (Oct 16, 2026), claude -p --model sonnet fails on macOS while Claude Desktop on the same Mac keeps working. A commenter on that issue says a launchd job “silently broke an automation for three days.” That’s the real cost here. Not the error. The silence.
Background subagents. Then there is #106631, was opened Nov 1, 2026 (UTC) on Claude Code 2.1.316 on Linux. Two background subagents about 20 minutes into a review both died with:
Agent terminated early due to an API error: Failed to authenticate: OAuth session expired and could not be refreshed (error type authentication_failed)The main session kept working the whole time. It’s Dwight’s fire drill. The building is technically fine, but half the office is gone and nobody knows why. The reporter says “Resuming each agent with SendMessage worked and kept its context.” Anthropic’s docs also say a background agent-view or Remote Control session that outlives the login “stops making progress once the credential expires and can’t recover until you sign in again” (authentication docs).
Claude Desktop. #97735 (Sep 28, 2026) describes a false version: the error overlay hides a reply that actually arrived, and “Reloading the app restores the “lost” response.”
All four issues were still open as of Nov 3, 2026. No fix version is published for the -p or subagent cases.
Fixes in order
Work down this list. Each one names its source, and nothing here involves sharing accounts or touching token files by hand.
1. Run /login (per docs). It’s the official fix. In an interactive session, type /login and finish the browser sign-in. For claude -p or the Agent SDK, Anthropic says to run claude in the same environment (same user, same machine, same config directory), complete /login, then rerun your command (errors reference). A commenter on #81937 confirms it: “Running /login within Claude (interactive) fixed it for me.”
2. If that loops, reset the login cleanly (per docs). Run /logout, close Claude Code, start claude again and sign in (troubleshooting, verified Nov 3, 2026). If the browser won’t open (SSH, WSL2, containers), press c to copy the login URL and open it on your local machine.
3. Update Claude Code (per changelog). Several login-loss bugs are fixed in the changelog, so an old build is a real suspect:
- 2.1.129: “Fixed OAuth refresh race after wake-from-sleep that could log out all running sessions”
- 2.1.136: fixed “a rare login loop where a concurrent credential write could overwrite a freshly-rotated OAuth token and force re-login”
- 2.1.265: “Fixed VS Code and SDK sessions occasionally requiring re-login when a session was closed while refreshing its token”
- 2.1.277: “Fixed being unexpectedly logged out when an older Claude Code build (for example an IDE extension’s bundled CLI) runs on the same machine as the current one”
- 2.1.317: “Fixed
claude auth statusexiting before a slow token refresh was saved, which could sign you out on the next run”
That 2.1.277 line matters. If you have an old standalone CLI next to a newer IDE extension or Desktop build (the #102811 setup was CLI 2.1.239 next to Desktop’s 2.1.295/2.1.299), update the old one so they stop fighting.
4. Close other Claude Code processes if the message is about refreshing (per docs). A different error, Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh…, is “usually transient; retry in a minute” (errors reference). Close stray sessions and retry before you re-login.
5. Check for an ANTHROPIC_API_KEY override (per docs). It doesn’t cause this error, but it changes who pays. In -p mode, “the key is always used when present” (authentication docs), and Anthropic’s help center says a set key means API charges instead of your subscription (help article, verified Nov 1, 2026). Run /status to see which login is active. If you didn’t mean to use the key, unset ANTHROPIC_API_KEY and remove it from your shell profile.
6. For long-running or headless jobs, use a one-year token (per docs). This is the real fix for automation. Run claude setup-token. It prints a “one-year OAuth token” that you set as CLAUDE_CODE_OAUTH_TOKEN (authentication docs). It needs a Pro, Max 5x, Ultra (formerly Max 20x), Team or Enterprise plan. Two catches: it “can only make model requests,” so no Remote Control or claude.ai connectors, and bare mode doesn’t read it. Store it like a password, in a secrets manager or your OS keychain, never in a repo. The #102811 commenter used exactly this setup for a launchd job. If you’d rather pay per token, use an ANTHROPIC_API_KEY instead, billed at API rates.
7. For background subagents, resume them after you re-login (reported in #106631). Per the reporter, SendMessage brought the dead agents back with their context. That’s a user report, not documented behaviour, but it’s cheap to try before you restart a 20-minute job.
“Failed to authenticate” and other login errors
Not every Failed to authenticate line is this one. Anthropic’s errors page has a separate “OAuth token revoked or expired” section for Failed to authenticate: OAuth token revoked… and API Error: 401 OAuth token has expired, and #81937 shows an older variant: Failed to authenticate. API Error: 401 … "OAuth access token has been revoked." The fix there is also /login. Since 2.1.287, the revoked-login message in -p starts with “Failed to authenticate” too, so read the rest of the line. If yours mentions an API key rather than OAuth, go to Claude Code invalid API key. If it’s a network drop, see Claude Code ECONNRESET. And if the error is about limits rather than logins, that’s Claude Code usage limit reached.
What you lose and what fixes it
| Situation | Work lost? | Fix |
|---|---|---|
| Interactive | No, re-login | /login |
claude -p job | That run fails | /login, rerun |
| Cron/CI | Every run | setup-token |
| Subagents | Stops mid-task | Re-login, resume |
| Desktop overlay | Reply hidden | Reload app |
| Refresh clash | No | Wait, retry |
Sources: errors reference and authentication docs (verified Nov 3, 2026); subagent row from #106631, Desktop row from #97735 (user reports, verified Nov 3, 2026).
Here’s what I’d do
If you only use Claude Code interactively, update it, run /login when it asks, and actually listen to the “expires in 3 days” warning. That’s it.
If anything runs unattended, stop relying on a browser login. A claude -p job that dies quietly for three days is how you end up explaining to your team why the nightly report is blank. Run claude setup-token, store the token properly, and set CLAUDE_CODE_OAUTH_TOKEN for the job. Add an alert on exit codes, because Claude Code won’t send you a postcard.
And honestly? I’m frustrated with Anthropic on this one. #81937 has been open since July with paying Max subscribers asking for headless runs that don’t need a babysitter. One commenter said they’d consider moving to OpenAI over it. The docs fix is clear, but “log in again every few days” isn’t a great answer for the people paying the most. If this keeps biting you, compare options in Claude Code alternatives or the AI coding tools comparison.
FAQ
What does OAuth session expired and could not be refreshed mean in Claude Code? Claude Code’s saved claude.ai login was rejected when it tried to renew it, so it cleared the credentials and you need to run /login again.
How do I stop Claude Code logging me out? Keep Claude Code updated, renew when it warns “Your login expires in 3 days”, and use claude setup-token with CLAUDE_CODE_OAUTH_TOKEN for unattended jobs.
Is it a Claude Code bug? Partly: Anthropic documents the expiry as expected behaviour, but open issues #81937, #102811 and #106631 report it hitting claude -p and background subagents while interactive sessions keep working.
Why does claude -p say Failed to authenticate: OAuth session expired and could not be refreshed? Non-interactive runs show this text instead of “Login expired · Please run /login”, so run claude in the same environment, complete /login, then rerun.
Does the error use up my plan’s usage? Anthropic doesn’t publish anything on that, so check /status and your usage page after you sign back in.
Sources
- Claude Code docs, Error reference (“Login expired”, “OAuth token revoked or expired”): https://code.claude.com/docs/en/errors (verified 2026-11-03)
- Claude Code docs, Authentication (expiry warning,
claude setup-token, precedence, credential storage): https://code.claude.com/docs/en/authentication (verified 2026-11-03) - Claude Code docs, Troubleshooting installation and login (“Reset your login”,
ANTHROPIC_API_KEYoverride): https://code.claude.com/docs/en/troubleshoot-install (verified 2026-11-03) - Claude Code CHANGELOG (2.1.129, 2.1.136, 2.1.265, 2.1.277, 2.1.287, 2.1.317): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md (verified 2026-11-03)
- GitHub issue #106631, background subagents killed by OAuth expiry: https://github.com/anthropics/claude-code/issues/106631 (verified 2026-11-03)
- GitHub issue #102811,
claude -pfails while Desktop works: https://github.com/anthropics/claude-code/issues/102811 (verified 2026-11-03) - GitHub issue #97735, false OAuth overlay in Desktop: https://github.com/anthropics/claude-code/issues/97735 (verified 2026-11-03)
- GitHub issue #81937,
claude -pOAuth expiry with interactive mode working: https://github.com/anthropics/claude-code/issues/81937 (verified 2026-11-03) - Claude Help Center, API key vs subscription billing: https://support.claude.com/en/articles/11145838 (verified 2026-11-01)