[DOCS] Troubleshooting missing macOS keychain guidance for Console login "Not logged in" errors

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/troubleshooting

Section/Topic

Permissions and authentication → Authentication issues / "Not logged in" or token expired, plus the /doctor guidance for diagnosing auth failures on macOS

Current Documentation

The troubleshooting page currently says:

### Authentication issues If you're experiencing authentication problems: 1. Run /logout to sign out completely 2. Close Claude Code 3. Restart with claude and complete the authentication process again

And for this symptom it says:

### "Not logged in" or token expired If Claude Code prompts you to log in again after a session, your OAuth token may have expired. Run /login to re-authenticate. If this happens frequently, check that your system clock is accurate, as token validation depends on correct timestamps.

The authentication page also says:

Storage location: on macOS, credentials are stored in the encrypted macOS Keychain.

And the /doctor summary currently says:

Run /doctor to diagnose issues. It checks: Installation type, version, and search functionality Auto-update status and available versions Invalid settings files (malformed JSON, incorrect types) MCP server configuration errors Keybinding configuration problems Context usage warnings (large CLAUDE.md files, high MCP token usage, unreachable permission rules) * Plugin and agent loading errors

No current page explains that Claude Console login on macOS can fail with "Not logged in" when the login keychain is locked or its password is out of sync, or that claude doctor now diagnoses this condition.

What's Wrong or Missing?

Changelog v2.1.94 says:

Fixed Console login on macOS silently failing with "Not logged in" when the login keychain is locked or its password is out of sync — the error is now surfaced and claude doctor diagnoses the fix

The current docs only cover generic re-login and token-expiry troubleshooting. They do not tell macOS users that Claude Console sign-in depends on the login keychain, that a locked or out-of-sync keychain can produce a misleading "Not logged in" failure, or that claude doctor is now the right way to identify this exact problem and recover.

For affected users, retrying /login is unlikely to help until they discover the local keychain issue.

Suggested Improvement

Add a macOS-specific troubleshooting subsection such as Console login fails on macOS with "Not logged in".

It should:

1. State that Claude Console credentials on macOS are read from the login keychain.
2. Explain that login can fail if the login keychain is locked or its password is out of sync with the macOS account password.
3. Tell users to run claude doctor first, and include the exact remediation Claude Code now surfaces for this condition.
4. Cross-reference the Authentication page so Console users know this applies to claude auth login --console / Console-account sign-in specifically.

A short note on the Authentication page would also help, for example: if Console login fails with "Not logged in" on macOS, run claude doctor and check the state of the login keychain.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/troubleshooting | Current auth troubleshooting only suggests logout/relogin or token expiry, and the /doctor summary does not call out auth/keychain diagnosis |
| https://code.claude.com/docs/en/authentication | Claude Console login steps plus the note that macOS credentials live in Keychain |
| https://code.claude.com/docs/en/setup | Tells users to run claude doctor for installation/configuration checks |
| https://code.claude.com/docs/en/cli-reference | Documents claude auth login --console and claude auth status, so Console-auth troubleshooting should align with these commands |
| https://code.claude.com/docs/en/commands | Documents /doctor, /login, and /logout at a high level |

Total scope: 5 pages affected

Source: Changelog v2.1.94

Changelog entry:

Fixed Console login on macOS silently failing with "Not logged in" when the login keychain is locked or its password is out of sync — the error is now surfaced and claude doctor diagnoses the fix