If Claude Code prints this, do exactly what the message says first — wait a minute and run the command again:
Failed to refresh OAuth token: another Claude Code process is refreshing it
or exited mid-refresh. This is usually transient; retry in a minute, and if
it persists close other Claude Code processes or sign in again.
In the common case that is the whole fix, and nothing is wrong with your account or your install.
Here is what the message is telling you. Before Claude Code renews your OAuth token it takes a short lock on the credential store, so that two sessions cannot write it at once and leave you with a half-written token. This error means the lock was already held when your session wanted it. There are only two ways that happens:
- A second session is genuinely refreshing right now. It finishes in seconds and releases the lock. Retrying works.
- A previous session died while holding the lock. Nothing will ever release it, so every command from now on prints this message. Retrying does not work.
The retry is therefore the diagnostic as well as the fix. If one retry clears it, stop here. If the second attempt fails the same way, you have a stale lock and the rest of this page applies.
Fix a stale lock
Step 1: Find every Claude Code process
The message says to close other Claude Code processes, and the reason people get stuck here is that they close the terminal windows they can see and miss the ones they cannot.
# macOS and Linux
pgrep -fl claude
# Windows PowerShell
Get-Process | Where-Object { $_.ProcessName -like "*claude*" }
Expect to find more than you opened. IDE extensions keep a background process alive independently of any visible panel, and so do MCP servers, background agents and any CI or cron job that shells out to claude.
Step 2: Close them all
Quit your editor completely rather than closing the Claude panel — a running editor restarts its background process immediately and retakes the lock as fast as you clear it. Then confirm nothing is left:
pgrep -fl claude || echo "none running"
If a process refuses to exit, end it explicitly and re-check:
pkill -f claude
pgrep -fl claude || echo "none running"
Step 3: Re-authenticate to rewrite the credentials
With nothing running, sign in again. This writes a fresh token and clears the lock state along with it:
claude auth login
Or, from inside a session, use the slash command:
/login
Then confirm:
claude auth status
Step 4: If it still fails, reset the credential state
If claude auth login itself reports the same locking error with no Claude Code process running anywhere, the stored state is inconsistent. Move it aside rather than deleting it, so you can restore it if this was not the cause:
mv ~/.claude/.credentials.json ~/.claude/.credentials.json.bak
claude auth login
Your settings, history and project configuration live elsewhere in ~/.claude and are untouched by this. On macOS, if the token is held in the login Keychain instead, search it for the Claude Code entry in Keychain Access and delete that item before logging in again.
Stop it recurring
Most repeat cases come from one of three setups.
Shared credentials across containers. Mounting your host ~/.claude into a devcontainer — or into several at once — gives independent Claude Code installs a single credential file with no coordination between them. They will contend indefinitely. Give each container its own configuration directory and authenticate it separately rather than sharing the host's.
A session on networked or synced storage. A ~/.claude on NFS, SMB, or a folder synced by Dropbox, iCloud Drive or OneDrive breaks the locking that this mechanism depends on, and the sync client can also restore a stale lock file after you clear it. Keep the configuration directory on local disk.
Unattended jobs running as you. A cron job, CI runner or scheduled agent invoking claude with your credentials will contend with your interactive sessions at unpredictable times. Give automation its own authentication rather than borrowing yours.
The error this is not
Two OAuth messages look similar and have opposite fixes:
| Message | What it means |
|---|---|
another Claude Code process is refreshing it | Lock contention during renewal. Your login is valid. Retry, then clear stale processes. |
OAuth session expired and could not be refreshed | The session genuinely lapsed and renewal was refused. You must sign in again. |
If yours is the second, OAuth token has expired covers it, including the API-key conflict and system-clock causes that make a valid login look expired.
Related guides
- OAuth session expired and could not be refreshed — the expiry case
- Where Claude Code configuration files are stored — what lives in
~/.claude - Claude Code permission errors — if the credential file cannot be written at all