[FEATURE] Warn when CLAUDE_CODE_OAUTH_TOKEN env var overrides credentials file

[GaryDean]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

When the CLAUDE_CODE_OAUTH_TOKEN environment variable is set, Claude Code silently uses it instead of credentials stored in ~/.claude/.credentials.json. This caused me weeks of troubleshooting and unexpected API billing charges.

I have a Max subscription ($200/month). Despite logging in correctly via claude login, my usage was being billed to my API account instead of my Max subscription allocation. Multiple complete reinstalls of Claude Code did not fix the issue.

The root cause: an old OAuth token from months ago was persisted in my system environment (loaded via shell profile scripts). This stale token silently overrode my fresh, valid Max subscription credentials in the credentials file.

The official documentation at https://support.claude.com/en/articles/12304248 only mentions ANTHROPIC_API_KEY precedence—there is no documentation warning that CLAUDE_CODE_OAUTH_TOKEN also overrides the credentials file.

Proposed Solution

1. Show a warning on startup when both CLAUDE_CODE_OAUTH_TOKEN env var AND ~/.claude/.credentials.json exist with different tokens:

   ⚠ Warning: CLAUDE_CODE_OAUTH_TOKEN environment variable is overriding credentials in ~/.claude/.credentials.json

2. Enhance /status output to show credential source:

   Authentication: OAuth (from environment variable CLAUDE_CODE_OAUTH_TOKEN)

   vs

   Authentication: OAuth (from ~/.claude/.credentials.json)

3. Update documentation to include CLAUDE_CODE_OAUTH_TOKEN in the environment variable precedence article alongside ANTHROPIC_API_KEY.

Alternative Solutions

Current workaround is to manually unset the environment variable:

unset CLAUDE_CODE_OAUTH_TOKEN

Or add to ~/.bashrc:

unset CLAUDE_CODE_OAUTH_TOKEN ||:

However, this requires users to first discover that the env var is the problem—which took me weeks of debugging and multiple reinstalls before identifying.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

1. User runs claude setup-token to get OAuth token for CI/CD or container use
2. User exports token: export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
3. Months later, user forgets about this or the token is persisted in system credential store
4. User logs into Claude Code with Max subscription via claude login
5. Fresh credentials saved to ~/.claude/.credentials.json with subscriptionType: "max"
6. Claude Code silently uses the old env var token instead of fresh credentials
7. User's usage is billed to API account, not Max subscription
8. User reinstalls Claude Code multiple times—problem persists because env var survives
9. User has no indication that env var is overriding their credentials file

Additional Context

Related issues:

• [BUG] Possible Issue: Environment Variables ANTHROPIC_AUTH_TOKEN and CLAUDE_CODE_OAUTH_TOKEN May Interfere with Local Interactive Mode #7855 - Environment variables ANTHROPIC_AUTH_TOKEN and CLAUDE_CODE_OAUTH_TOKEN interfere with local interactive mode
• [BUG] Auth conflict: Both a token (CLAUDE_CODE_OAUTH_TOKEN) and an API key (apiKeyHelper) are set #11587 - Auth conflict warning exists for API key + OAuth token, but not for OAuth env var + OAuth credentials file
• [Bug] Claude Code fails to recognize MAX subscription tier - defaults to Pro restrictions #6955 - MAX tier recognition issues

Environment:

• Claude Code version: 2.0.76
• OS: Ubuntu 24.04
• The stale token was stored in a systemd-creds encrypted credential store (/etc/credstore/) which survived Claude Code reinstalls

Technical note:
Claude Code already has conflict detection for ANTHROPIC_API_KEY vs OAuth. Similar logic could detect when CLAUDE_CODE_OAUTH_TOKEN env var differs from the token in ~/.claude/.credentials.json.

[github-actions]

Found 1 possible duplicate issue:

1. [BUG] Possible Issue: Environment Variables ANTHROPIC_AUTH_TOKEN and CLAUDE_CODE_OAUTH_TOKEN May Interfere with Local Interactive Mode #7855

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[GaryDean]

This is not a duplicate of #7855. Here's why:

Aspect	#7855 (Bug)	#16238 (This Feature Request)
Type	Bug report	Feature request
Symptom	Authentication fails with errors	Authentication succeeds silently with wrong credentials
User experience	Claude Code won't start	Claude Code works, but bills wrong account
Visibility	User sees error message	User sees nothing wrong
Impact	Can't use Claude Code	Unexpected API charges for weeks/months

The key difference:

• [BUG] Possible Issue: Environment Variables ANTHROPIC_AUTH_TOKEN and CLAUDE_CODE_OAUTH_TOKEN May Interfere with Local Interactive Mode #7855: Setting env vars causes Claude Code to fail → user knows something is wrong immediately
• [FEATURE] Warn when CLAUDE_CODE_OAUTH_TOKEN env var overrides credentials file #16238: Stale env var silently overrides valid credentials → user has no idea, gets billed to wrong account

#7855 is about broken authentication. This issue is about silent credential precedence causing billing surprises with no warning.

The feature I'm requesting would prevent the scenario in #7855 from being confusing -- if Claude Code warned users that an env var is overriding their credentials file, both issues would be addressed.

[adeze]

this is what chatgpt and I were able to figure out with this issue on macOS after half a day. now it works for me, but I haven't tried /login again . deleting .claude/settngs.json seemed to be the actual fix since I tried unsetting the variables only which did nothing .

⸻

🔍 Detailed Diagnosis & Resolution (macOS / Claude Code)

Summary

Claude Code was intermittently failing with:
• 401 token expired or incorrect
• 429 insufficient balance / no resource package
• Repeated auth conflict warnings

This occurred even though billing was enabled and valid API keys existed. The root cause was multiple overlapping credential sources and stale persisted state, which caused non-deterministic credential selection and sometimes resulted in API clients being created without an Authorization header.

⸻

🧪 Evidence Observed

1. Logs showed missing Authorization header

Claude logs repeatedly contained lines similar to:

Creating client ... has Authorization header: false

This confirms the client was sometimes constructed with no usable credential at all.

Later background calls failed with:

401 {"error":{"message":"token expired or incorrect"}}

Meaning a stale/invalid credential was still being attempted.

⸻

2. Multiple credential sources were active simultaneously

At different times the system had all of the following active:

A. Environment variables
• ANTHROPIC_AUTH_TOKEN (stale / invalid)
• Sometimes no stable ANTHROPIC_API_KEY
• Different shells (Warp, VS Code terminal, login shells) loaded env inconsistently.

B. Claude CLI persisted state
• ~/.claude/settings.json contained managed login state and cached credentials.
• Even after unsetting env vars, this file continued to influence auth.

C. Desktop / Electron persistence
• ~/Library/Application Support/Claude contained:
• Cookies
• IndexedDB
• Local Storage
• Session Storage
• Network Persistent State
• These cached OAuth/session artifacts could silently rehydrate stale tokens.

D. Managed keys created on every /login
• Each /login created a new claude_code_key_* in the “Claude Code” workspace.
• Old keys accumulated and some were never used.
• One key successfully billed small usage; others failed.
• This made it difficult to know which identity was actually being used.

⸻

3. Workspace billing was healthy (not the real problem)

The “Claude Code” workspace showed:
• Active monthly spend limit
• Non-zero spend already recorded
• Billing banner enabled

Despite this, failures still occurred because the CLI was often authenticating with:
• An expired token, or
• No credential at all, or
• A stale managed key

This made the errors look like billing problems when they were actually identity resolution problems upstream.

⸻

4. Multiple runtimes increased entropy

The system had:
• Native Claude install
• npm-installed preview at one point
• VS Code extension embedding its own runtime

Each could read/write shared auth state differently and contributed to nondeterministic behavior.

⸻

✅ Deterministic Fix That Resolved the Issue

The problem was fully resolved by forcing Claude into a single, stateless credential path:

Remove all token-based auth

unset ANTHROPIC_AUTH_TOKEN
unset CLAUDE_CODE_OAUTH_TOKEN

Delete persisted CLI state

rm -f ~/.claude/settings.json

(Optional but helpful during cleanup)

rm -rf "~/Library/Application Support/Claude"

Then run Claude without using /login, relying only on a stable API key:

export ANTHROPIC_API_KEY="sk-...stable key from Default workspace"
claude

Results:
• No auth conflict warnings
• No new managed keys created
• No new settings.json recreated (stateless mode)
• Authorization header consistently present
• 401 / 429 errors disappeared

⸻

🧠 Root Cause

Claude Code currently allows multiple overlapping credential mechanisms to coexist:
• OAuth / token auth
• Managed login keys
• Persisted CLI state
• Desktop app caches
• Environment API keys
• Optional apiKeyHelper

When more than one is present, credential precedence becomes opaque and unstable. Stale state can persist across sessions and even across shells, leading to inconsistent authentication behavior.

⸻

🛠️ Suggested Improvements
1. Document and support a first-class “API-key-only / stateless mode”.
2. Provide a single command to fully reset all local credential state (CLI + desktop caches).
3. Make credential precedence explicit and observable in diagnostics.
4. Avoid silently rotating managed keys on every /login or surface this clearly.
5. Detect and warn when Authorization header is missing before attempting requests.

[chris-lower]

I had this problem. I'm not sure how the environment variable was set, but I hit my limit on one account, logged in with another account with oauth, and claude code would keep giving me the limit error. I searched and found this issue. I unset the environment variable and it immediately started working with the new account.

I would have been nice if maybe during the /login it would have said that there was an override in place. I didn't even know this environment variable existed so I had no idea to even look for it.