Claude CLI 401 Unauthorized Refresh Token Issue

Symptom: claude commands fail with 401 Unauthorized and the message "refresh token was already used. Please log out and sign in again."

Cause: The refresh token expired after being consumed by another session or a background process. Refresh tokens are single-use credentials.

Fix: Run claude auth login to refresh authentication without running a logout command first.

Why claude login alone did not clear the 401

I was running a pipeline command when every subsequent CLI call failed. The terminal returned this exact output:

Error: 401 Unauthorized
  Message: "Authentication failed: refresh token was already used. Please log out and sign in again."
  Code: "AUTH_ERROR"

The error text explicitly instructs me to log out. I spent roughly ten minutes searching the terminal for a logout function. The prompt only showed AUTH_ERROR. I assumed clearing old sessions was required first. That assumption blocked progress. The instructions in the error message describe your token state, not the recovery step. You do not need to run claude auth logout. The token is already invalid. Executing a logout command on an expired session adds unnecessary steps without changing the result. You only need to sign in again.

How to verify a consumed refresh token state

I checked available commands by running claude auth --help. It listed three options: login, logout, and status. I used claude auth status to verify the broken state. It confirmed the session was inactive. This command is useful for verifying your fix works immediately after re-authenticating.

The core issue lies in how refresh tokens work. A refresh token is a single-use credential that keeps your session alive without asking for fresh credentials repeatedly. If any background script or another terminal window consumes it, the token becomes invalid. Your active session loses its validity instantly. The error message mentions log out because the system expects you to clean up after yourself, but that cleanup function only works on active sessions. When the token is already consumed, you must bypass the logout step entirely.

What happens when background scripts burn tokens

The CLI functioned normally until a pipeline execution triggered the failure. No manual logout occurred beforehand. This pointed to an unseen consumer. Long-running scripts or suspended processes often hold onto refresh tokens in the background. When they execute, they use the token to verify their identity against the API. Once that happens, your active terminal session can no longer use it. The token is burned.

I resolved the issue by running claude auth login. The terminal opened a browser window to complete the authentication flow. Alternatively, it prompted me directly in the terminal for an authentication code. I completed the prompt. All commands immediately resumed working. The 401 error disappeared. I verified everything was normal by running claude auth status. It showed an active session. The entire process took less than two minutes once I stopped looking for a logout function.

How to prevent token exhaustion during pipeline runs

I learned a few concrete things from this breakdown. Session management requires understanding how tokens behave under the hood. I will keep this checklist for future pipeline maintenance:

Ignore log out instructions when you see a consumed token error.
Run claude auth login immediately to generate a fresh token.
Use claude auth status to verify your session is active before running pipelines.
Check for long-running background scripts that might be burning refresh tokens.

Written from real hands-on experience, drafted with AI assistance.