[BUG]

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

OAuth Token Expiration Issue in Claude Code

Issue Summary

Claude Code sessions are interrupted by OAuth token expiration during long work sessions, causing loss of progress and requiring users to start completely new sessions. The /login command does not resolve the issue in the current session.

Error Message

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"OAuth token has expired. Please obtain a new token or refresh your existing token."},"request_id":"req_011CWwqkfTQzty2cH3EQcTZ1"} · Please run /login

Current Behavior

1. During long Claude Code sessions (typically after 1-2 hours), the OAuth token expires

1. All API calls fail with 401 authentication errors

1. Running /login in the current session does NOT fix the issue

1. The only solution is to exit and start a completely new session

1. All context and progress from the current session is lost

Expected Behavior

1. OAuth tokens should either:

• Have a longer lifetime that accommodates typical development sessions (4+ hours)

• Auto-refresh transparently when nearing expiration

• Provide a working in-session refresh mechanism (e.g., /login should work)

1. Users should be warned before token expiration (e.g., "Token expires in 10 minutes")

1. If session restart is required, there should be better session recovery mechanisms

Impact

• High severity: Interrupts active development work and causes loss of progress

• User frustration: Forces context switching and rebuild of work state

• Productivity loss: Time spent reconstructing context and re-implementing work

Technical Details

Why /login Doesn't Work

According to the official documentation, /login is designed for "switching Anthropic accounts," not refreshing the current session's authentication token. The token is bound to the session at creation time and cannot be refreshed within the session.

Available Configuration

The documentation mentions CLAUDE_CODE_API_KEY_HELPER_TTL_MS environment variable for custom refresh intervals, but this only applies to apiKeyHelper (custom credential scripts), not OAuth-based authentication through Claude.ai accounts.

Documentation Gap

The public documentation does not specify:

• The exact OAuth token lifetime

• How to configure or extend token lifetime for Claude.ai accounts

• Clear guidance for handling token expiration during long sessions

• Best practices for session management to avoid this issue

Reproduction Steps

1. Start a Claude Code session using OAuth authentication (Claude.ai account)

1. Work continuously for 1-2 hours

1. Observe 401 authentication error

1. Attempt to run /login - observe it does not resolve the issue

1. Exit and start new session - observe it works with fresh token

Requested Features/Fixes

Priority 1: Immediate Relief

1. Automatic token refresh: Implement in-session token refresh that happens transparently before expiration

1. Make /login work in-session: Allow /login to refresh the current session's token, not just switch accounts

1. Expiration warnings: Warn users 10-15 minutes before token expiration

Priority 2: Configuration

1. Configurable token lifetime: Allow users to request longer-lived tokens (e.g., 8-hour tokens for development sessions)

1. Document token behavior: Clearly document OAuth token lifetime and refresh behavior

Priority 3: Better Recovery

1. Session persistence: Allow /resume to continue from an expired session after re-authentication

1. Context preservation: Save session context to allow seamless recovery after token refresh

Workarounds (Current)

1. Frequent commits: Commit work to git regularly to preserve progress

1. Context notes: Keep notes of current task in a file

1. Shorter sessions: Plan to restart sessions every 60-90 minutes

1. Manual session recovery: Use /resume with new sessions (requires manual context rebuild)

Environment

• Platform: macOS (Darwin 23.6.0)

• Claude Code: Latest version (as of 2026-01-09)

• Authentication: OAuth via Claude.ai account

• Model: Claude Sonnet 4.5

References

• Claude Code GitHub Issues: https://github.com/anthropics/claude-code/issues

• Official Documentation: Token refresh mechanism not clearly documented for OAuth users

---

Reporter: User experiencing mid-session token expiration

Date: 2026-01-09

Severity: High - Blocks continued work and causes productivity loss

What Should Happen?

Priority 1: Immediate Relief

1. Automatic token refresh: Implement in-session token refresh that happens transparently before expiration

1. Make /login work in-session: Allow /login to refresh the current session's token, not just switch accounts

1. Expiration warnings: Warn users 10-15 minutes before token expiration

Priority 2: Configuration

1. Configurable token lifetime: Allow users to request longer-lived tokens (e.g., 8-hour tokens for development sessions)

1. Document token behavior: Clearly document OAuth token lifetime and refresh behavior

Priority 3: Better Recovery

1. Session persistence: Allow /resume to continue from an expired session after re-authentication

1. Context preservation: Save session context to allow seamless recovery after token refresh

Error Messages/Logs

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"OAuth token has expired. Please obtain a new token or refresh your existing token."},"request_id":"req_011CWwqkfTQzty2cH3EQcTZ1"} · Please run /login

Steps to Reproduce

Current Behavior

1. During long Claude Code sessions (typically after 1-2 hours), the OAuth token expires

1. All API calls fail with 401 authentication errors

1. Running /login in the current session does NOT fix the issue

1. The only solution is to exit and start a completely new session

1. All context and progress from the current session is lost

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.0.76

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other

Additional Information

Using claude desktop app