Skip to main content
Deterministic recovery guide for authentication, account switching, quota, and command-routing issues.

​
Quick Recovery (60 Seconds)

If you encounter any authentication or account health issues, start here:
1

Run the doctor command

codex auth doctor --fix
This attempts to auto-repair unhealthy accounts and refresh expired tokens.
2

Verify account health

codex auth check
Confirms that accounts are healthy and tokens are valid.
3

Test live quota

codex auth forecast --live
Verifies real-time quota availability.
If the issue persists, try re-authenticating: 
codex auth login

​
Common Issues

Likely cause: Wrapper path conflict or incorrect installation.Solution:
1

Check command routing

# Windows
where codex

# macOS/Linux
which codex
# or
command -v codex
2

Verify installation

codex multi auth status
npm ls -g codex-multi-auth
3

Reinstall if needed

If an old scoped package is still active:
npm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-auth
Likely cause: Normal OAuth browser-first flow.Solution: This is expected behavior. Complete the authentication in the browser and return to the terminal. The OAuth callback server runs at http://127.0.0.1:1455/auth/callback.
The browser-based OAuth flow is required by ChatGPT for secure authentication. No credentials are transmitted via the command line.
Likely cause: Stale Codex CLI state cached in memory.Solution:
1

Re-run the switch command

codex auth switch <index>
2

Restart terminal session

Close and reopen your terminal to clear cached state.
3

Verify active account

codex auth status
Likely cause: Worktree was using a different legacy path key before shared storage was added.Solution: Run codex auth list once in the worktree to trigger migration into repo-shared storage.Background: Linked Git worktrees now share accounts via resolveProjectStorageIdentityRoot. Legacy worktree-keyed account files are auto-migrated on first load. Legacy files are retained only if the canonical write fails (to prevent data loss).
Likely cause: Stale auth payload from an expired or incomplete OAuth flow.Solution: Re-login the affected account:
codex auth login
This refreshes the entire authentication payload including the id_token.
Likely cause: Token pair rotated elsewhere (e.g., logged in from another machine or browser).Solution: Re-login the affected account to obtain a new token pair:
codex auth login
OAuth refresh tokens are single-use. Reusing a refresh token from a different session invalidates the current session.
Likely cause: Refresh token is no longer valid (typically after 30+ days).Solution: Re-login the affected account:
codex auth login
The proactive refresh guardian (enabled by default) should prevent this in active sessions. If you see this error frequently, ensure proactiveRefreshGuardian: true in your settings.
Likely cause: Entire account pool has stale or expired tokens.Solution:
1

Attempt auto-repair

codex auth doctor --fix
2

Add a fresh account

If auto-repair fails, add at least one fresh account:
codex auth login
3

Verify recovery

codex auth list
codex auth check
Likely cause: Another process (possibly a stale codex instance) is using port 1455.Solution: Stop the conflicting process and retry login.Find the process:
# macOS/Linux
lsof -i :1455

# Windows
netstat -ano | findstr :1455
Kill the process and run codex auth login again.
Likely cause: Network latency or SSE stream interruption.Solution: Increase the stream stall timeout:
export CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=90000
Or edit ~/.codex/multi-auth/settings.json:
{
  "pluginConfig": {
    "streamStallTimeoutMs": 90000
  }
}
Default is 45000ms (45 seconds). Minimum is 1000ms.
Likely cause: Quota exhaustion across all accounts.Solution:
1

Check live quota

codex auth forecast --live --model gpt-5-codex
2

Wait for quota replenishment

If preemptive quota is enabled (default), requests will be deferred up to preemptiveQuotaMaxDeferralMs (2 hours default).
3

Add more accounts

For higher throughput, add additional accounts to the pool:
codex auth login

​
Diagnostics Pack

When filing an issue or debugging locally, gather this information: 
codex auth list
codex auth status
codex auth check
codex auth verify-flagged --json
codex auth forecast --live
codex auth fix --dry-run
codex auth report --live --json
codex auth doctor --json
Include the output in your issue report along with: 
codex --version
npm ls -g codex-multi-auth
And the failing command with full terminal output.

​
Verify Installation and Routing

Confirm that the plugin is installed correctly and command routing is functional: 
# Check which codex binary is active
where codex       # Windows
which codex       # macOS/Linux

# Verify version
codex --version

# Check auth status
codex auth status
codex multi auth status

# Verify package installation
npm ls -g codex-multi-auth
If an old scoped package is still active: 
npm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-auth

​
Soft Reset

If all else fails, perform a soft reset to clear account and settings state:
This will remove all stored accounts and settings. You will need to re-authenticate after the reset.

​
PowerShell

Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\openai-codex-flagged-accounts.json" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\settings.json" -Force -ErrorAction SilentlyContinue
codex auth login

​
Bash

rm -f ~/.codex/multi-auth/openai-codex-accounts.json
rm -f ~/.codex/multi-auth/openai-codex-flagged-accounts.json
rm -f ~/.codex/multi-auth/settings.json
codex auth login
After the reset: 
codex auth check
codex auth forecast --live --model gpt-5-codex

​
Issue Report Checklist

When filing an issue, attach these outputs:
  • codex auth report --json
  • codex auth doctor --json
  • codex --version
  • npm ls -g codex-multi-auth
  • Failing command and full terminal output
  • Operating system and Node.js version
This information accelerates troubleshooting and ensures reproducible diagnostics.

Build docs developers (and LLMs) love

Get started for freeTalk to us