[FEATURE] Warn users when ANTHROPIC_BASE_URL overrides OAuth/subscription credentials
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
When users have both OAuth credentials (Max/Pro subscription) AND custom environment variables like ANTHROPIC_BASE_URL in their settings.json, Claude Code silently uses the custom URL instead of Anthropic's API.
This causes confusing 404 "model not found" errors even though the user has a valid subscription. The .credentials.json correctly shows subscriptionType: "max", but API calls fail because they're being routed to a non-Anthropic endpoint.
I faced this issue after experimenting with a local LLM setup. I had leftover ANTHROPIC_BASE_URL in my settings.json. It took hours to debug because there was no warning that my subscription credentials were being overridden.
Multiple users have reported similar confusion in issues #20976, #16489, #22972, and #16238.
Proposed Solution
Claude Code should detect and warn users when:
- Valid OAuth/subscription credentials exist in
.credentials.json, AND ANTHROPIC_BASE_URLis set to a non-Anthropic endpoint in settings or environment
Suggested warning message:
Warning: ANTHROPIC_BASE_URL is set to a custom endpoint.
Your subscription credentials will not be used.
Run `/logout` and remove ANTHROPIC_BASE_URL from settings to use your Max/Pro subscription.
This warning should appear:
- On startup when the conflict is detected
- When running
/doctorcommand - In the UI status bar (instead of just showing "API Usage Billing")
Alternative Solutions
Currently there's no warning. Users have to:
- Manually inspect settings.json and .credentials.json
- Search GitHub issues to find similar problems
- Trial and error to identify the conflict
Other tools like VS Code warn when conflicting settings are detected.
Priority
High - Significant impact on productivity
Feature Category
Configuration and settings
Use Case Example
Example scenario:
- User sets up Claude Code with Max subscription - works fine
- User experiments with local LLM (Ollama) and adds ANTHROPIC_BASE_URL to settings.json
- User switches back to using Claude Code normally
- User forgets to remove the custom URL setting
- Claude Code shows "API Usage Billing" and all models return 404
- User spends hours debugging, checking subscription, re-logging in
- User finally discovers the leftover setting was overriding their subscription
With this feature:
- Step 5 would show a clear warning about the configuration conflict
- User immediately knows to remove the custom URL
- Problem solved in seconds instead of hours
Additional Context
Related GitHub Issues:
- #20976 - Max plan shows as 'API Usage Billing' in CLI
- #16489 - Claude Code uses API billing despite forceLoginMethod setting
- #22972 - CLI shows 'Claude API' despite OAuth account configured
- #16238 - Similar authentication confusion
The fix is straightforward:
- Check if OAuth credentials exist with valid subscriptionType
- Check if ANTHROPIC_BASE_URL is set and doesn't point to api.anthropic.com
- If both conditions true, show warning
This small addition would prevent significant user frustration and reduce support burden.
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗