Error reference
What each Claude Code error message means and how to fix it, from API, auth and network failures to CLI, plugin, tool, background session and config warnings.
This is the lookup page for error text. Search it for the words in your message (Ctrl+F or Cmd+F works well, since most entries quote the stable part of the message), read the one-line cause, and apply the fix. Messages are grouped by where they come from. Many have changed wording between releases; where an old version behaves differently in a way that matters, the entry says so.
Two habits save time before you dig in. First, /status shows which credential, settings sources and model a session is really using, and it resolves a surprising share of auth and limit errors. Second, Claude Code has usually already retried before showing you anything, so a message on screen means retrying has run out, not that it never started.
Note: Claude Code's own messages sometimes contain a long dash. To keep this page searchable in plain text, quotes below include only the part of each message on one side of that dash.
How automatic retries work
Claude Code retries transient failures up to 10 times with exponential backoff. What gets retried depends on how far the response had got.
Retried:
- Server errors, overloads and timeouts before any of the response has streamed.
- A server error or overload after Claude finished thinking but before any text or tool call (up to two retries).
- Dropped connections before Claude completed any part of its response, including its thinking. If the drop comes after thinking but before any text or tool call, Claude Code retries twice quickly, then ends the turn with
Connection lost before a response was produced. A connection broken by your computer sleeping counts as a dropped connection (Connection lost while your computer was asleep, orYour computer went to sleep before a response was produced). - A stalled stream (headers arrived, no content, or thinking done with nothing after it): one extra retry outside the normal budget, then
The response stalled before a response was produced. - A streaming request that never gets response headers within the first-byte deadline: one re-send, then No response from API.
- A response the output content filter stops before thinking finishes or any text starts: one re-send.
- Temporary 429 throttles, including ones without your plan's quota headers. Not a gateway's spend-limit 429.
- A request whose input plus
max_tokensexceeds the context limit: retried with a smallermax_tokens, or compacted when no reduction fits. - Expired Google Cloud credentials, or AWS credentials that fail to load: cached credentials dropped and two retries.
- A 401 or 403 while an
apiKeyHelperscript supplies the key: the script reruns and the request retries with fresh output.
Not retried:
- TLS certificate validation failures (a TLS-inspecting proxy, missing
NODE_EXTRA_CA_CERTS, expired certificate). These show on the first attempt. Transient TLS conditions like handshake timeouts still retry. - A failure after Claude completed a block of text or a tool call. Re-running could execute tools twice, so Claude Code keeps what was finished and continues from it; see The response above may be incomplete.
- A failure after the response finished. The turn simply ends normally.
- A Bedrock stream with the wrong content-type, a non-streaming retry that returns something that isn't an API message, and requests your organisation's policy check denied.
What the spinner shows
During retries you see Retrying in Ns · attempt x/y after a label. The label names the real reason straight away when you can act on it (network down, TLS handshake, rate limit), otherwise API error until the third attempt. For a 529 it also tells you where to check status: status.claude.com for the Anthropic API, or the provider or gateway host otherwise.
If no data arrives for 20 seconds, Waiting for API response · will retry in … · check your network appears before any retry. The request hasn't failed yet; the countdown runs to the point where Claude Code aborts the stalled connection. During an advisor consultation the threshold is 90 seconds, because long reviews legitimately send nothing for a while. If the banner keeps returning, treat it as a network problem.
Tuning retries
| Variable | Default | Effect |
|---|---|---|
CLAUDE_CODE_MAX_RETRIES | 10 | Attempts before giving up. Capped at 15 unless the watchdog is on. Lower it in scripts to fail faster |
CLAUDE_CODE_RETRY_WATCHDOG | unset | Set to 1 in unattended runs to retry 429 and 529 capacity errors indefinitely, and raise the default retry count for other transient errors to 300 (roughly three hours) with no cap. A 429 reporting a spend limit or exhausted usage credits still fails at once |
API_TIMEOUT_MS | 600000 | Per-request timeout in ms. Also caps how long the retry waits for headers. A positive value under 11 seconds turns the first-byte deadline off |
CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES | unset | Limit on re-sends of a timed-out non-streaming request. Each attempt times out after 300 seconds locally, or API_TIMEOUT_MS if set. Needs v2.1.285+ |
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS | unset | First-byte deadline for streaming requests, clamped between 10 seconds and 30 minutes. Needs v2.1.242+ |
Server errors
These come from the inference provider behind your endpoint, not from your prompt or account (with a couple of exceptions noted).
| Message | Cause | What to do |
|---|---|---|
API Error: 500 Internal server error (or any 5xx) | An unexpected failure inside the API. A proxy's HTML error page shows as the status plus the page title, such as API Error: 502 Bad Gateway | Check status.claude.com or the provider status page the message names. Wait a minute and type try again. If it persists with no incident posted, run /feedback |
API Error: Repeated 529 Overloaded errors | The API is at capacity for everyone. Not your quota | Wait and retry. Capacity is per model, so /model to another model keeps you going. You may be prompted with Opus is experiencing high load, please use /model to switch to Sonnet (or the Fable equivalent) |
Request timed out | No reply before the deadline (10 minutes by default), often under load or for a very long answer | Retry. Raise API_TIMEOUT_MS for slow networks or proxies |
API Error: No response from API (waited ...) | No response headers arrived within the first-byte deadline, twice | Send again. If a proxy holds responses until they complete, raise API_TIMEOUT_MS (and on Bedrock also CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS). If only the first attempt keeps timing out, raise CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS |
Agent terminated early due to an API error: <detail> | A subagent's request failed terminally, for example on a usage limit | Look up the detail after the colon on this page, fix that, then ask Claude to retry or resume the subagent |
The response above may be incomplete
A stream broke after Claude had already completed some text or a tool call. Claude Code keeps the finished work, runs any finished tool calls, and appends one of these:
| Variant | What broke |
|---|---|
Server error mid-response | An overload or 5xx partway through |
Connection lost mid-response | The connection dropped, or a proxy closed the body early |
Your computer went to sleep mid-response | Sleep broke the connection |
The response stopped arriving | The connection stayed open but went silent, so the idle watchdog aborted it |
Part of the response never arrived | A stream event was dropped between the API and Claude Code |
The response stream was malformed | A damaged or out-of-order event arrived |
In an interactive session, read what's on screen (an interrupted final block is discarded) and reply continue. In -p text output you get the last completed text block plus the notice; JSON formats put it in the result field. Non-interactive runs and subagents first prompt Claude to continue up to three times when the cut-off reply was text only, and show the notice only once those are used up.
If the stream breaks before Claude has started any text or tool call, you won't see this notice. Claude Code re-issues the request (ending with Part of the response never arrived and no response was produced or The response stream was malformed and no response was produced if that keeps happening), or falls back to a non-streaming request. With that fallback switched off via CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, you get API Error: Content block not found, Content block already closed or Stream event unreadable.
Auto mode errors
When the auto mode classifier can't produce a decision, the action isn't auto-approved. Reads, searches and edits inside your working directory skip the classifier and keep working.
| Message | Cause | What to do |
|---|---|---|
<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> (sometimes with (rate-limited), (overloaded), (server error), (timed out) or (connection failed)) | The classifier model failed | Retry after a few seconds; Claude usually does this itself. Repeated timeouts or connection failures point to your network. On Bedrock, if it never clears, your account can't invoke the named model: check IAM, or for Mantle IDs contact your AWS account team |
Auto mode could not evaluate this action and is blocking it for safety | The classifier's reply couldn't be parsed | Retry. Run claude --debug if it repeats |
Same, plus a safety check separate from auto mode blocked this request because of earlier conversation content | An API safety filter tripped on earlier conversation content | Not a verdict on the action, and retrying won't help. Switch permission mode so you can approve manually, or start a fresh conversation. These don't count towards auto mode's pause thresholds |
Auto mode classifier transcript exceeded context window | The conversation is too big for the classifier | Approve or deny the fallback prompt, and /compact. In -p with no permission prompt tool, the action is skipped |
The server-side auto mode classifier gave no verdict | Under server-side review, the server gave no verdict | Retry. After 10 in a row you get Auto mode is unavailable and the turn stops: send another message, check whether a gateway is truncating or rewriting streams, set CLAUDE_CODE_AUTO_MODE_SERVER=0 to use local classifier requests, or switch out of auto mode |
Usage limits
Most of these mean a quota on your account or plan is used up. Three are different: the temporary server throttle, the 1M-context entitlement check, and the unanswered usage-credits prompt.
| Message | Cause | What to do |
|---|---|---|
You've hit your session limit / weekly limit / Opus limit / Sonnet limit | Your subscription's rolling allowance ran out. Session and weekly limits cover all models; Opus and Sonnet limits cover one family | Wait for the reset time shown. For a family limit, /model to another family (expect no cache hits on the switch). /usage shows limits; /usage-credits buys more on Pro and Max or requests it from your admin on Team and Enterprise. Interactive claude.ai sessions can wait and continue automatically after the reset |
Usage credits required for 1M context | You selected a [1m] model and your plan only offers 1M context through usage credits | /model to the variant without [1m], or turn usage credits on and restart. If it appeared because context grew past 200K, Claude Code compacts automatically. CLAUDE_CODE_DISABLE_1M_CONTEXT=1 hides 1M variants |
the prompt to confirm went unanswered (Fable usage credits) | A consent prompt for billing Fable to usage credits closed with nobody answering, typical in Remote Control, background or teammate sessions | Answer it where the session runs (attach from agent view for background sessions), /model to a model that doesn't use credits, or lengthen dialogExpiry |
Server is temporarily limiting requests (not your usage limit) | A short server-side throttle | Wait and retry |
Request rejected (429) | Your API key's, Bedrock project's or Google Cloud project's rate limit | Check /status for a stray ANTHROPIC_API_KEY, raise your tier in the provider console, and reduce concurrency (CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, fewer parallel subagents, a smaller model) |
You've hit your monthly spend limit (or individual, org's monthly, team's shared budget, channel's monthly, individual usage limit) | Usage credits hit a spend cap. The text after the dot says who can raise it | Pro and Max: raise it in claude.ai usage settings or /usage-credits. Team and Enterprise: an admin raises it, and /usage-credits asks them. If a reset time is shown you can wait instead |
spend limit reached (daily; resets ...) | A Claude apps gateway operator's cap. Not retried | Wait for the reset or ask the operator. spend limit unavailable means the gateway couldn't read its records and usually clears itself |
Credit balance is too low | Your Console org is out of prepaid credits, or a Console key is being used when you meant your subscription | On a subscription, check /status for an API key row and unset ANTHROPIC_API_KEY. Otherwise add credits in Console billing and consider auto-reload |
Could not update your spend limit | The server rejected a change you made from the limit prompt | If a reason is shown, pick a value that satisfies it. The generic form (Press Enter to retry) may be transient. Otherwise change it in claude.ai billing |
Authentication errors
Run /status first: it shows which credential is active, and that decides which fix applies.
Claude login and API keys
| Message | Cause | What to do |
|---|---|---|
Not logged in · Please run /login (Desktop: Authentication required) | No usable credential | /login. Signing in from another window using the same config directory also fixes an open interactive session. For CI, use an apiKeyHelper |
Could not resolve authentication method | A background or cloud worker started with no credential | Make sure the credential is set in the environment that launches the worker. Upgrade if older than v2.1.176 |
Invalid API key · Fix external API key | The key was rejected, or blocked locally because it contains a character a header can't carry | Check for typos and revocation. Look for stale keys loaded by direnv or .env files (env | grep ANTHROPIC). Or unset the key and /login |
Your apiKeyHelper script is failing | The helper exited non-zero, timed out, printed nothing, or printed something other than a key | Run the helper yourself. It must print only the key (printable ASCII, up to 16,384 characters) and exit 0. /status shows the failure. /login doesn't help while the helper is configured |
Invalid auth token, Invalid ANTHROPIC_CUSTOM_HEADERS, Invalid request header from the environment | A value contains a line break, NUL or character above U+00FF (curly quotes and zero-width spaces are common culprits from pasting) | Retype the value around the reported position. Keep ANTHROPIC_CUSTOM_HEADERS to one Name: Value per line |
Your ANTHROPIC_API_KEY belongs to a disabled organization, or This organization has been disabled | A stale environment key overrides your subscription | Unset the key and remove it from your profile. If the hint says Update or unset, you have no saved login, so also /login |
Your organization has disabled API key authentication | Your Console admin turned off API keys | Remove ANTHROPIC_API_KEY or the apiKeyHelper setting, then /login with claude.ai |
Your organization has disabled Claude subscription access for Claude Code | A server-side org setting (code oauth_org_not_allowed in SDK and -p) | Ask an admin to enable it, or use a Console API key |
Routines are disabled by your organization's policy | An Owner turned routines off | Ask an Owner to enable Routines in the Claude Code admin settings, or use scheduled tasks |
OAuth token revoked / OAuth token has expired | The API rejected your saved login, or an expired CLAUDE_CODE_OAUTH_TOKEN | /login. For a long-lived token, generate a new one with claude setup-token |
API Error: 401 Invalid authentication credentials | The account or organisation behind a valid-looking credential was disabled or the credential revoked | If /status shows an active API key, rotate or unset it. Otherwise /login once. If it returns, the account or org is inactive; ask your admin. Through a gateway, the text is the gateway's |
Login expired · Please run /login | Renewal failed and Claude Code cleared the saved login, so nothing is sent | /login. /status shows a Login row reading Expired in this state |
Could not refresh your login because another Claude Code process is refreshing it | Another process held the shared refresh lock | Retry in a minute, close other Claude Code windows, or /login |
Couldn't save your login | The credential store refused the write (often a locked macOS Keychain) | Unlock the Keychain and /login again |
Failed to start OAuth callback server | Claude Code couldn't listen on 127.0.0.1 | Use claude setup-token elsewhere and set CLAUDE_CODE_OAUTH_TOKEN, or an API key. In a sandbox, allow local listeners |
Claude login not accepted | A cloud session start got a 401 | /login and try again |
Artifacts need a claude.ai login | No claude.ai credential usable for artifacts | /login and choose Claude account with subscription. Remove any credential the message says takes precedence |
Not signed in to the Cloud gateway, or Administrator policy requires a Cloud gateway sign-in | Managed settings set forceLoginMethod to "gateway" or forceLoginGatewayUrl | /login on the Cloud gateway screen. For the startup form, remove the credential the message names |
Your account is on hold | The account is suspended (code account_on_hold) | Use the link to view details or appeal. Another account or API key still works meanwhile |
Anthropic profile login expired | The credential profile (from ANTHROPIC_PROFILE or discovered) has expired with no refresh | Sign in to the profile again (via /login and the Console option for profiles written by the keyless sign-in or ant auth login), or stop using the profile |
OAuth token does not meet scope requirement: user:profile | Your token predates a newer scope | /login; no need to log out first |
claude.ai rejected the session token | A claude.ai connector request was rejected because of your Claude Code login | /login, then reconnect the connector in /mcp |
Remote Control sign-in messages
When Remote Control loses its credentials it stops, your local session keeps running, and a line beginning Remote Control disconnected names the reason: Claude.ai login expired, Claude.ai login was rejected, OAuth token unavailable, OAuth token refresh failed, JWT refresh failed: no OAuth token, or Signed out of Claude. Run /login, then /remote-control. Messages ending run /login to restore Remote Control reconnect by themselves after you sign in.
Two related stops:
signed-in claude.ai account or organization changed on this machine: you switched accounts elsewhere. Run/remote-controlto start a session as the new account, or/loginback first.Remote Control stoppedwiththe app running this session is now signed in to a different Claude accountoris signed out of Claude: the hosting desktop app or IDE changed. Sign in there and turn Remote Control back on, or start a new session under the new account.
Remote Control is only available when using Claude via api.anthropic.com means the session goes through Bedrock, Vertex, a custom ANTHROPIC_BASE_URL, ANTHROPIC_UNIX_SOCKET or a cloud gateway. Unset the variable it names (check the env block of your settings too).
MCP server sign-in
| Message | Cause | What to do |
|---|---|---|
MCP server "<name>" needs you to sign in again | The server's sign-in expired or was revoked | /mcp, select the server, sign in |
rejected the credential from its headersHelper | The helper's output was refused (after one rerun) | Fix the helper, then reconnect in /mcp |
rejected the Authorization header in its config | A static header is wrong | Update it, then reconnect |
needs additional permissions (scope: "<scope>") | The server returned 403 insufficient_scope | Re-authenticate from /mcp. If you pinned oauth.scopes, add the scope first |
This server's URL is missing or not a valid URL | The url doesn't parse | Fix it, or set the variable its ${VAR} refers to |
Issuer mismatch in authorization response (RFC 9207) | The redirect's iss doesn't match the server's metadata, which is what a mix-up attack looks like | Retry, then report to the server operator. MCP_SDK_GENERATION=v1 skips the check but removes the protection |
Refusing to send credentials to non-https token endpoint | The token endpoint isn't HTTPS or loopback | Serve it over HTTPS. MCP_SDK_GENERATION=v1 allows plain HTTP for every server until you exit |
Cloud providers and gateways
| Message | Cause | What to do |
|---|---|---|
AWS credentials expired or invalid | 401 from Claude Platform on AWS or the Mantle endpoint | Run the refresh command named (such as aws sso login --profile ...), or /login then 3rd-party platform then Claude Platform on AWS · refresh credentials when awsAuthRefresh is set. Check with aws sts get-caller-identity |
AWS authentication failed | 403 from AWS, or 401 from Bedrock. Could be an expired token or a missing IAM permission | Refresh credentials, then check IAM and that the model is enabled for your account and region |
Google Cloud credentials expired or invalid | 401 from Agent Platform | gcloud auth application-default login (or your gcpAuthRefresh command), or fix GOOGLE_APPLICATION_CREDENTIALS. Through a gateway with CLAUDE_CODE_SKIP_VERTEX_AUTH, refresh the gateway token |
Google Cloud authentication failed | 403: missing IAM role or model not enabled | Check roles and model access in Google Cloud's Agent Platform |
Microsoft Foundry authentication failed | 401 or 403 from Foundry | Rotate ANTHROPIC_FOUNDRY_API_KEY, mint a new ANTHROPIC_FOUNDRY_AUTH_TOKEN, or az login. Then check RBAC on the resource |
Could not load AWS credentials / Could not load Google Cloud credentials | The local credential chain produced nothing (code cloud_credential_error) | Run your provider sign-in and retry |
AWS default-chain credential resolve timed out | The chain hung for 60 seconds, often a credential_process waiting for input or an IMDS that never answers | Test aws sts get-caller-identity. Sign in first. Raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS if an MFA flow genuinely needs longer |
Timed out after 60s waiting for AWS, A request to AWS timed out | A call during the Bedrock setup wizard stalled | Same checks as above; fix network or proxy first |
Cloud gateway session expired, Cloud gateway <url> no longer accepts this session | The gateway session can't be renewed | /login |
Sign-in timed out while waiting for you to continue | You left the gateway account confirmation open too long | /login again and confirm promptly |
Gateway refused the request | 403 from the gateway or its upstream | Signing in won't help; ask the gateway administrator |
Network and connection errors
| Message | Cause | What to do |
|---|---|---|
Unable to connect to API, Connection refused (ECONNREFUSED), Can't reach the API server (ENOTFOUND), No internet route (EHOSTUNREACH), Couldn't connect through your proxy (ERR_PROXY_TUNNEL), Connection dropped (ECONNRESET) | The TCP connection failed | Test with curl -I https://api.anthropic.com (curl.exe on Windows). Set HTTPS_PROXY behind a proxy. If curl works but Claude Code doesn't, look for a leftover ANTHROPIC_BASE_URL pointing at a dead proxy, a bad /etc/resolv.conf (common in WSL), stale VPN utun interfaces on macOS, or Docker Desktop intercepting traffic |
Unable to connect to Anthropic services | First-run check couldn't reach api.anthropic.com or platform.claude.com within 10 seconds | Check the proxy variable it names. Claude Code may also not be available in your country. Skipped when managed settings force gateway login |
Socket is closed | Usually a Windows corporate proxy dropping a tunnel mid-response | Update to v2.1.214+, which retries it. If it continues, check the proxy |
API returned an empty or malformed response (HTTP 200) | A non-streaming retry got a 200 that isn't an API message: an HTML page, empty body, or captive portal | Read the Response: clause to see who answered. Complete Wi-Fi sign-in pages. Fix the gateway hop. CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 turns this fallback off |
Streaming response ended before any complete data was received | A proxy swallowed or transformed the stream; Claude Code retried without streaming | Make the proxy pass streaming bodies and headers through untouched |
Bedrock streaming response has content-type "..." | Something between you and Bedrock rewrote the binary event stream | Pass application/vnd.amazon.eventstream through unmodified. CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 hides the error but falls back to slower non-streaming requests |
SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY), Self-signed certificate detected, SSL certificate error | A TLS-inspecting proxy or private CA. Not retried | Point NODE_EXTRA_CA_CERTS at your CA bundle. Never set NODE_TLS_REJECT_UNAUTHORIZED=0. See Network configuration |
403 with x-deny-reason: host_not_allowed | A cloud session or routine hit its network allowlist | Edit the environment: change Network access from Trusted to Custom and add the domain (optionally keeping the default list), or choose Full. Org-shared environments need an Owner |
artifact content fetch failed (proxy refused the connection: HTTP 407/403/...) | Your proxy refused the CONNECT to *.frame.claudeusercontent.com | 407: add credentials to the proxy URL. 403: ask for the host to be allowed. Or add .frame.claudeusercontent.com (no broader) to NO_PROXY |
The cloud environments service returned an empty response / unexpected format | Usually a service-side blip | Retry; check status.claude.com if it persists |
Couldn't reconnect to your Remote Control session | Resuming couldn't confirm the remote session | /remote-control to retry, or start fresh with claude --remote-control |
N sessions ended while this machine was offline | The server cleaned up the Remote Control environment | Recover work from any kept worktrees, then run claude remote-control again |
Couldn't share the transcript. | The 8 MiB upload couldn't be reduced enough, failed, or the local archive couldn't be written | Use /feedback instead |
Couldn't send feedback | The /feedback upload failed (or not signed in) | /login if asked, retry, or file on GitHub |
Request errors
Context and size
| Message | Cause | What to do |
|---|---|---|
Prompt is too long (interactive: Context limit reached · /compact or /clear to continue) | The conversation plus attachments exceeds the context window. Bedrock says Input is too long for requested model; a Claude apps gateway says capability_rejected: prompt_too_long | /compact, or /clear. Run /context to see what's using space, /mcp disable <name> for unused servers, and move bulky CLAUDE.md content into path-scoped rules. Turn auto-compact back on if you disabled it (the message tells you when) |
Prompt is too long · automatic compaction failed: <error> | Compaction itself failed | Fix the named error first |
Prompt is too long · this conversation is a single exchange | Nothing earlier to summarise; the request is mostly system prompt, tools or attachments, or your one prompt | /clear and start smaller, or reduce tools and attachments |
Context exceeds the ...-token limit by ... tokens (in /context) | You're past the window | /compact or /clear. The past the ...-token compaction window form just means compaction is due |
Request too large (max 32MB) | The raw body exceeded 32MB, usually images and attachments | /compact drops accumulated attachments. If it says compacting cannot make it fit, press Esc twice to go back past the big turn, or /clear. Reference files by path rather than pasting |
Image was too large | Over the API's size or dimension limits (8000px longest edge, or 3000px with more than 20 images in context) | Claude Code swaps in a placeholder and carries on. Resize or crop before pasting |
Unable to resize image | Couldn't decode or shrink it (CMYK JPEG, animated WebP, damaged file, unreadable dimensions, over 2000x2000) | Re-save as PNG, JPEG, GIF or WebP, or resize it yourself |
PDF too large (max 100 pages, 20MB), PDF is password protected, The PDF file was not valid | The PDF can't be attached | Read a page range instead, extract text with pdftotext, or remove the password |
pdftoppm is not installed | Page-range reads need poppler | brew install poppler or apt-get install poppler-utils |
Malformed requests
| Message | Cause | What to do |
|---|---|---|
Extra inputs are not permitted ... context_management | A gateway stripped the anthropic-beta header | Forward that header, or set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 |
tools.N.custom.input_schema: JSON schema is invalid, Property keys should match pattern | An MCP tool's schema fails validation (N is its position, not a name) | Update to v2.1.216+, which excludes such tools. Otherwise disable servers until it stops; property names must be 1 to 64 characters of letters, digits, _, ., - |
tool_use.name: String should have at most 200 characters | An overlong tool name in history | claude update and resume; newer versions trim it |
due to tool use concurrency issues, orphaned tool_result, duplicate tool_use ID, unexpected tool_use_id, thinking blocks ... cannot be modified | History is out of sequence | On Opus 4.7 or 4.8, update first (pre-v2.1.156 bug). Then /rewind or Esc twice to a checkpoint before the bad turn |
Invalid data in redacted_thinking block | An earlier thinking block was refused | Handled automatically from v2.1.282. On older versions, update and resume, or /clear |
[Unsupported tool content removed] | A proxy-produced tool block was stripped when loading a session | Nothing to do. If every resumed turn fails with server_tool_use.name: Input should be, update |
role 'system' must precede an 'assistant' message | A proxy inserted its own system message | Test without the proxy and report it to its operator |
Invalid encrypted_content in search_result block and related encrypted_index, Failed to decrypt web search result content, encrypted_stdout | History contains hosted web-search or code-execution content the API can't decrypt, usually from a gateway | Web-search forms recover automatically from v2.1.282. Otherwise /rewind or /clear, and tell the gateway operator |
Models, thinking and effort
| Message | Cause | What to do |
|---|---|---|
There's an issue with the selected model | Unknown model name or no access | /model interactively, --model or ANTHROPIC_MODEL in -p, model in SDK options. Prefer aliases like sonnet. Hunt down stale IDs set elsewhere (see Model configuration) |
Model "..." is not a recognized model id. Did you mean ... | A switch passed something that can't be a model ID (often a display name) | Pick from /model. Update if the alias is newer than your version |
Model '...' not found | The endpoint couldn't confirm the name | Use /model or an alias; check your provider's catalogue. SDK users can call supportedModels() |
Couldn't confirm model "..." with the API | The 5-second verification got no answer | Try again; check connectivity |
API error: ... · model not changed | Verification failed for another reason, such as 429 | Act on the server's explanation and retry |
Claude Opus is not available with the Claude Pro plan | Your plan doesn't include it | Choose another model. After upgrading, /logout and /login to refresh the plan |
Claude Code ... does not support this model; version ... or newer is required, or older than the minimum version required by your organization's policy | Your binary is too old (claude_code_version_too_old) | Update whichever binary made the request: claude update, the desktop app, the VS Code extension, or the SDK package. On the stable channel you may need the latest channel |
Model ... is restricted by your organization's settings, Model ... is not available. Your organization restricts model selection. | Disabled by an admin, or excluded by availableModels / deniedModels | /model to an allowed one; remove the restricted ID from flags, env or frontmatter; ask an admin |
Can't switch to the default model | Managed deniedModels or an exact availableModels blocks what Default resolves to, or managed settings couldn't be read | Pick an allowed model by name, or ask your admin |
Model switch ... blocked by a PreModelSwitch hook | A hook denied it, timed out, wanted confirmation the session can't show, or managed plugin hooks couldn't be checked | Address the reason given; fix or extend a hanging hook's timeout; switch interactively; run claude --debug for load failures |
couldn't save it as your default | Writing ~/.claude/settings.json failed (read-only, or invalid JSON) | The session switched anyway. Fix the file and switch again |
is less capable than the current main model / Advisor will not activate / cannot advise | Your advisor ranks below the main model | Choose a stronger advisor or a smaller main model |
thinking.type.enabled is not supported for this model | Your version predates the model's minimum (Opus 4.7: v2.1.111, Opus 4.8: v2.1.154, Sonnet 5: v2.1.197, Opus 5: v2.1.219, Opus 5.5: v2.1.280, Sonnet 5.5: v2.1.284) | claude update (move to the latest channel if needed) or upgrade the SDK package, or pick an older model |
Effort '<level>' isn't available with thinking turned off | Effort above high with thinking disabled | /effort high, or turn thinking back on (unset MAX_THINKING_TOKENS=0, remove "alwaysThinkingEnabled": false) |
max_tokens must be greater than thinking.budget_tokens | Thinking budget leaves no room for the answer | Raise CLAUDE_CODE_MAX_OUTPUT_TOKENS |
Safety and policy refusals
| Message | Cause | What to do |
|---|---|---|
API Error: <model> can't help with this. Start a new session to continue. | A Usage Policy check on the whole conversation. Resuming carries the same content | Esc twice or /rewind to before the triggering turn and rephrase, or /clear. In -p, start a new session without --continue; another model may help |
<model>'s safeguards flagged this message (or this session) | Content was flagged as a cybersecurity topic. On Bedrock, Vertex and Foundry you get the Usage Policy message instead | Apply to the Cyber Verification Program if your work needs it; /feedback for false positives; /rewind to keep working |
Details: `[reasoning_extraction]` | Something asked Claude to reproduce its internal reasoning verbatim, perhaps in CLAUDE.md, a skill, agent prompt, output style or MCP description | Remove that instruction. claude --safe-mode shows whether a customisation is the trigger. Asking for an explanation or summary is fine |
API Error: Output blocked by content filtering policy | The output filter stopped the reply | Rephrase or /rewind |
Installation errors
| Message | Cause | What to do |
|---|---|---|
Installation was killed before it could finish (exit code 137) | Usually the Linux OOM killer; install needs about 512MB free | Free memory, add swap, or use a larger instance. See Troubleshoot installation |
The connection dropped while downloading the update (attempt 3/3: ...) | Three download attempts failed (drops, stalls or checksum failures) | Run claude update again, set HTTPS_PROXY if needed, ask IT to allow full downloads from downloads.claude.ai, and run claude doctor |
Download timed out: exceeded the total deadline | The download took over 10 minutes. Not retried | Retry from a faster network |
Command-line errors
Flags and input
| Message | Cause | What to do |
|---|---|---|
--bg and --print conflict | A print run can never become an attachable background session | Use claude --bg "<task>" or claude -p "<task>", not both |
Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file | Two forms of the same flag | Keep one. (Before v2.1.283 the main system prompt pairs conflicted too) |
Error: Invalid --agents configuration: | Bad JSON, a schema problem, or a name starting with -. Checks run in order, up to 20 lines shown | Fix each listed problem. --agents takes a JSON object, or a file path only with --print (-p) and --agents file not found are the file-path variants |
Error: --json-schema is not a valid JSON Schema: ... (also is not valid JSON, must be a JSON object) | The schema didn't compile | Fix the keyword the diagnostic names. format is accepted as an annotation. See Headless |
Error: Settings file exceeds the 2MiB limit / Cannot use settings file (Not a regular file ...) | Bad --settings target | Point at a normal JSON file under 2 MiB |
Error: Input must be provided either through stdin or as a prompt argument when using --print | stdout isn't a terminal (PowerShell ISE, IDE output panes), so claude ran non-interactively, or -p had no prompt | Use a real terminal, or pass a prompt: claude -p "..." |
Claude Code can't read the keyboard here: stdin is not a terminal | Interactive mode with piped input on Windows, or no /dev/tty elsewhere | Run directly in a terminal, or add -p (works with --continue and --resume) |
Error: Input contained only whitespace / Blank prompt | A prompt with no visible text | Check the variable or file your script builds the prompt from |
Error: stream-json input carried over 256M characters with no newline | Non-JSON data piped into --input-format stream-json, or one giant message | Each message must be one newline-terminated JSON line; drop the flag for plain text |
Unknown command: /<name> | Typo, unavailable command (platform, plan, auth), or an uninstalled plugin or MCP prompt. Only interactive terminals reject unknown names; elsewhere the text goes to Claude | Use the suggestion, or type / to browse; check the commands reference for requirements |
Directories, trust and environment
| Message | Cause | What to do |
|---|---|---|
The current directory no longer exists / Can't read the current directory (EACCES) | Started from a deleted or unreadable directory | cd somewhere real, or cd "$PWD" if it was recreated. For macOS EPERM in Desktop, Documents, Downloads or iCloud, restart the terminal and grant it access under Privacy & Security > Files and Folders |
Temp directory ... Refusing to use it, or ENOSPC ... mkdir '/tmp/claude-<uid>' | Can't create the private temp dir, or something suspicious is already there (symlink, wrong owner, bad mode) | Free space, remove the named entry itself (not its target), chmod 0700, or set CLAUDE_CODE_TMPDIR |
couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded | /add-dir on a subdirectory whose real path can't be confirmed | Check it's a real directory inside the working directory. File access is unaffected |
Error: Workspace not trusted (Remote Control) | claude rc couldn't ask about trust, for example with redirected I/O or a tiny terminal | Run claude rc or claude there once and accept trust. Home directory trust is never saved, so use a project directory |
`<flag>` before `remote-control` is not carried over | A global flag like --settings or --permission-mode placed before the verb | Move Remote Control's own options after the verb (claude remote-control --permission-mode <mode>) |
Cloud sessions cannot be created from a --restricted session | They wouldn't enforce restricted mode | Work locally, or start an unrestricted session |
Cloud sessions are disabled by your organization's policy | allow_remote_sessions is off (also blocks /teleport, /remote-env, /web-setup) | Ask an Owner. Couldn't verify your organization's policy means check your network and restart |
`claude import` is not yet available in this build | The feature flag is off: fresh install, third-party provider or gateway, or telemetry-related variables disable flag fetching | Start a session once and retry, or set things up manually |
Could not read Claude Code config | ~/.claude.json doesn't parse | Run claude with no arguments to reset it, or fix the JSON |
MCP commands
| Message | Cause | What to do |
|---|---|---|
Could not import <server>: Invalid name ... | Claude Desktop allows names claude mcp doesn't | Rename to letters, digits, hyphens and underscores, or add it directly with claude mcp add |
Cannot add MCP server to scope: managed | Managed scope comes only from managedMcpServers | Use local, user or project |
Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide | strictPluginOnlyCustomization locks mcp | Install a plugin that provides it, or ask an admin |
is Anthropic-hosted and doesn't support local OAuth | Hosts such as gmail.mcp.claude.com sign in only through claude.ai | claude mcp remove <name>, then connect it on claude.ai |
Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes | Something odd at .mcp.json | Replace it with a normal JSON file or delete it |
MCP server "<name>" was not saved to / was not removed from | The change wasn't in ~/.claude.json when read back (read-only file or sandbox) | Make it writable or run outside the sandbox, then repeat |
MCP server "<name>" may not have been saved / removed | Couldn't read the file back to confirm | Check with claude mcp get <name> and repeat if needed |
Server rejected the Authorization header minted by the configured headersHelper | 401 or 403 with a helper-supplied header; no OAuth fallback | Run the helper the way Claude Code would and fix its output, then Reconnect |
Error: MCP tool ... (passed via --permission-prompt-tool) not found | The server never connected within MCP_TIMEOUT (30 seconds), or the name is wrong | Check claude mcp list, the mcp__<server>__<tool> name, or raise MCP_TIMEOUT |
OAuth callback port <port> is already in use | A fixed port (MCP_OAUTH_CALLBACK_PORT or --callback-port) is taken | Find the process with lsof -ti:<port> -sTCP:LISTEN (Windows: netstat -ano | findstr :<port>), or register another port |
No available ports for OAuth redirect | Nothing can listen on 127.0.0.1 | Allow local listeners in security software or the sandbox |
Skills, review and GitHub
| Message | Cause | What to do |
|---|---|---|
Shell command failed for pattern "..." from /security-review | origin/HEAD doesn't exist (single-branch clone, empty remote, no remote) | git remote set-head origin <default-branch> (fetch the branch first if needed), or git fetch origin && git remote set-head origin --auto. The same message applies to any skill whose injected command fails |
Shell command permission check failed for pattern "..." | A skill's injected command wasn't permitted | Pre-approve it with allowed-tools; see Skills |
Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found | Bash-only skill on a machine without Git Bash | Install Git for Windows or set shell: powershell |
Diff is too large for ultrareview / PR #<N> is too large | Over the file or line limits; no free run used | Pass a closer base (/code-review ultra develop) or split the change. See Ultrareview |
Could not find merge-base with <branch> | No shared commit with the base | Pass the right base, or git fetch --unshallow origin |
Your checkout has no branches (detached HEAD only) | Nothing to bundle | git checkout -b <name> |
Ultrareview clones <owner>/<repo> ... and none is connected, GitHub isn't connected to your Claude account | No GitHub account linked | /web-setup, or connect at claude.ai/connect-github, then wait a minute |
Your connected GitHub account can't see <owner>/<repo> | App not installed or wrong account | /web-setup with a gh login that can see it, or install the Claude GitHub app |
The GitHub App preflight failed transiently | Bundle upload failed and the GitHub check hit a transient error | Retry shortly |
Not uploading this working tree: core.ignoreCase ... (also core.attributesFile, attr.tree) | The upload can't honour that git setting, so encrypted-by-filter files might leak | Apply the fix in the message's last sentence |
IP allowlist, requires single sign-on, or Conditional Access policy blocking Claude | A GitHub organisation policy | Allow Anthropic's IPs, reconnect GitHub and Authorize the org, or ask the Entra admin |
Single sign-on authorization needed (/install-github-app) | Your gh token isn't SSO-authorised | gh auth refresh -h github.com -s repo,workflow, or configure SSO on your PAT |
Sessions and UI
| Message | Cause | What to do |
|---|---|---|
Failed to resume the conversation. | The transcript couldn't be read | Retry with claude --resume <session-id>; update if older than v2.1.285; otherwise start fresh |
No conversation found with session ID: <id> | Typo, transcript deleted after the retention period (30 days by default), other machine, or duplicate copies | Use claude --resume and Ctrl+A to search every project. -p and SDK sessions aren't in the picker. See Sessions |
Windows reported an error (EBADF) | Security or encryption software intercepted the transcript read | Exclude %USERPROFILE%\.claude\projects (or your CLAUDE_CONFIG_DIR) from scanning |
Cannot switch renderers while work is running in the background / in this session | /tui restarts the process and would lose background work or session-only restrictions | Wait or stop tasks via /tasks, or switch from a session without those restrictions |
Couldn't open Claude Desktop | open or rundll32 failed | Open the app yourself and retry /desktop |
Couldn't read/back up/update your Zed keymap, isn't a readable list of keybindings | /terminal-setup left keymap.json alone | Paste the block from the message yourself, or fix the file's syntax |
Skill usage reports are not available on this connection. | /skill-doctor over Remote Control | Run it on the host machine |
Custom output styles can't be selected over Remote Control or from a relayed message | Only built-in styles are allowed there | Pick a built-in, or set outputStyle locally. See Output styles |
Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load | Setting sources exclude local | Add local, or set outputStyle in a file the session loads |
/recap only runs when you ask for it yourself in this session | The request came via Slack, Teams, a project thread, a routine or another program | Run /recap yourself in the session |
Plugin errors
| Message | Cause | What to do |
|---|---|---|
`plugin eval` is currently in early access / currently unavailable | Version older than v2.1.269, or switched off server-side | claude update; for the second, try later |
Marketplace "<name>" is registered from an untrusted source | A reserved name not sourced from github.com/anthropics | claude plugin marketplace remove <name> and re-add from the official source |
"<name>" is another spelling of "<reserved>" | Looks like a reserved name | Rename, or remove the ignored entry |
Claude Code refuses the marketplace name / Marketplace name impersonates an official Anthropic/Claude marketplace | Impersonating name | Remove it (this uninstalls its plugins) or wait for a rename |
Marketplace "<name>" is already added from a different source | Name clash | Install from the existing one by name, or remove it first |
references ${user_config.*} in a shell-form command (also monitors and headersHelper) | Config values could be executed by a shell | Use exec form with args, or read $CLAUDE_PLUGIN_OPTION_<KEY>; read values inside scripts |
Plugin archive integrity check failed | Downloaded archive doesn't match its sha256 pin | Publishers: recompute with shasum -a 256. Users: /plugin marketplace update <name> and retry |
path escapes plugin directory | A component path or symlink leads outside the plugin, or uses backslashes on macOS/Linux | Move the file inside, use ./ and forward slashes, copy instead of symlinking |
path could not be checked (ELOOP/EIO/ESTALE/EACCES) | The OS errored on a plugin path | Fix the loop, remount the share or restore permissions, then /reload-plugins |
marketplace entry path does not stay inside the marketplace directory, Plugin source path refused | Absolute, climbing, network, backslash or escaping-symlink entry, or a relative entry in a URL-only marketplace | Use a plain relative source such as ./plugins/my-plugin, or add the marketplace from git |
Failed to load marketplace configuration / Marketplace configuration file is corrupted | ~/.claude/plugins/known_marketplaces.json is unreadable or wrong shape | Repair it, or replace with {} and re-add marketplaces |
Plugin "<name>@synced" is required by your organization | An org-required synced plugin | Ask a claude.ai admin |
"<plugin>" was not uninstalled: it is still switched on in <file> | A settings file still enables it | Remove it from enabledPlugins in that file, then uninstall again |
More plugin issues live in Plugin troubleshooting.
Tool errors
Claude sees these as tool results and corrects most of them on its own. You only need to act when one keeps recurring.
| Message | Cause | What to do |
|---|---|---|
Error: No such tool available: <name> | Wrong name (case matters, so read vs Read), an MCP server still connecting or disconnected, or a name trimmed at 200 characters | Usually nothing. If MCP tools keep failing, check /mcp |
Agent '<name>' would be spawned with zero tools | Every tools entry was unrecognised, unavailable to subagents, or matched nothing in this session | Fix the entries, or delete the tools field to give the agent the default set. See Subagents |
File is covered by a Read deny rule in your permission settings | Edit or Write on a path you denied for Read | Narrow the rule, or add a matching Edit deny to block NotebookEdit too |
cannot contain null bytes (\0) | A path argument had a NUL | Nothing; Claude retries |
subagent_type is required: the general-purpose agent is not available | Built-ins disabled with CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1, or an Agent(...) allowlist excludes it | Usually nothing; otherwise allow general-purpose |
this write left the memory index at MEMORY.md ... over its ... read limit | Auto memory's index passed 200 lines or 25KB, so the tail won't load | Let Claude compact it into one line per entry with detail in topic files. See Memory |
pkill: refusing to run | On Linux, the pattern would kill Claude Code itself | Narrow the pattern, or use pkill -P $$ |
Failed to write to <name>'s inbox (and plan, permission and shutdown variants) | An agent team mailbox write failed (disk, permissions or lock) | Resend; check space and that ~/.claude/teams is writable |
Its agent definition was not restored: the folder ... is not trusted | A teammate's agent file came from an untrusted folder | Run claude there once and accept trust |
Message too large for cross-session delivery | Over 1,048,576 serialised characters | Summarise, split, or send a file path. See Cross-session messaging |
Too many messages to this session just now | A burst hit the recipient's rate limit | Batch remaining content into one message |
Cross-session message was dropped at the recipient session's inbox | Queue full, too fast, duplicate, or a relay loop was cut | Assume it wasn't seen; send fewer, larger messages; type into a session yourself to break a loop |
Refusing to send: reply target is a symlink / cannot vet reply target | The recipient's socket path can't be trusted | Usually nothing; investigate what created the link |
Refusing to read/write/search <path>: its symlink resolution changed after permission was checked (and related could not be determined, is a symbolic link, Refusing to write through symlink, into symlinked directory, permission check expired, ripgrep was found only by name on PATH) | A path's real location couldn't be confirmed between the permission check and the operation | Usually nothing. Find whatever keeps rewriting a link; install ripgrep so rg resolves to an absolute path; update if Windows sandboxes (pre-v2.1.265) or macOS screenshots (pre-v2.1.273) trigger it |
task output swap refused, Command killed: its output file was replaced or could no longer be verified | Something replaced or linked files in Claude Code's temp directory | Update to v2.1.260+, then restart with CLAUDE_CODE_TMPDIR set to a fresh directory, or remove the stray link or directory itself |
Your disk quota is full ... (EDQUOT), ... is full (ENOSPC), Command output was lost: the temp filesystem ... is full / is out of inodes | The temp filesystem or your quota is exhausted, so output was lost | Delete files (many small ones for inodes), or set CLAUDE_CODE_TMPDIR elsewhere, then rerun |
the source file is not valid UTF-8 text / has the replacement character U+FFFD | An artifact source isn't clean UTF-8 | Usually Claude fixes it. Write an intended U+FFFD as � |
Not published: that file is on a network share | UNC or /net path | Copy locally, or on Windows map a drive and pass it with --add-dir at launch |
Reading a local file from outside this session's connected folders ... needs the approval card | Cowork session that can't ask you | Copy the file into a connected folder as a regular file |
WebFetch cannot fetch localhost or other hostnames without a dot | By design | Claude uses curl via Bash instead |
The safety check for domain ... is rate-limited, Unable to verify if domain ... is safe to fetch | WebFetch's domain check against api.anthropic.com failed | Continue without the page, allowlist api.anthropic.com, or set skipWebFetchPreflight: true |
Background session errors
These come from background sessions and from worktree isolation checks.
| Message | Cause | What to do |
|---|---|---|
Can't open MCP settings while no terminal is attached to this background session (and /install-github-app) | Dialogs need an attached terminal. The session shows under Needs input | Attach from agent view and rerun, or use /mcp enable, disable or reconnect <server> |
blocked because the path is spelled in a form that cannot be safely resolved | Worktree guard can't verify the path (symlinks with .., device or network forms, unreadable parents) | Usually nothing; Claude retries with the direct path. Edit symlink targets by their real path |
blocked because the path is network-shaped | UNC or /net path with a local checkout | Use the local path |
is isolated in the worktree <path>, but this command ... Refusing to run it | The command targets the main checkout, or uses constructs like ${!name} that can't be verified | Split into plain commands run from the worktree; act on the main checkout yourself |
This session has no saved transcript | Backgrounded session stopped before its first reply finished | The original conversation is intact; claude respawn <id> starts this one fresh |
Can't open (running in another terminal), This conversation is already open in another running Claude session | Another process holds the transcript | Use that process, or exit it and retry |
This session's saved conversation is no longer on disk | Transcript cleaned up while the service was off | claude rm <id> or claude respawn <id> |
kept <id>, unpushed commits on "<branch>" | Deleting would lose commits that exist on no remote | Push or merge them, or use the printed --discard-unpushed command |
terminal host process died | The host process under the background service died | Press Enter on the row, or claude attach <id> again. Shell-command rows aren't rerun automatically |
Session isn't responding | No output for about ten seconds | Press Enter again, or claude stop <id> then claude attach <id> |
Session <id> was stopped while the respawn was in flight | Someone stopped it mid-restart | Reopen or claude respawn <id> if that wasn't you |
This session was running agent '<name>', which is no longer available | The custom agent file is gone or its folder untrusted; default tools apply | Re-create the agent, or resume with --agent <name> |
CLAUDE_CODE_PROCESS_WRAPPER: launcher ... | The launcher value isn't usable, or it didn't exec | Point it at an executable that ends with exec "$@", then claude daemon stop --any |
EUNKNOWN: unknown error, uv_spawn (Windows) | A restriction policy blocked a program, or an npm reinstall was mid-flight | Update to v2.1.212+, wait for npm, or ask your admin about AppLocker or Group Policy |
EACCES: permission denied, posix_spawn, Claude Code is being updated by npm on this machine | npm was replacing the binary | Retry when the update finishes; otherwise check permissions or reinstall |
exited before it became reachable | The background service crashed at start | Fix the quoted line. On Windows with nothing on stderr every time, delete ~/.claude/daemon.lock |
working directory no longer exists or is not accessible | Directory removed during start | Recreate it or dispatch from elsewhere |
Workspace not trusted. (dispatch) | No trust and no way to ask | Run claude there and accept trust; home-directory and could not be resolved on disk variants explain themselves |
Wrapper and IDE errors
| Message | Cause | What to do |
|---|---|---|
Error: Claude Code process exited with code N | The underlying claude exited non-zero; the real error is in its output | In VS Code, click View output logs. In SDK apps, catch the error (see Agent SDK troubleshooting). Run claude in a terminal in the same project to reproduce. A Windows 4294967295 exit at a turn boundary is handled quietly |
Could not locate the Claude CLI on PATH (VS Code, PowerShell) | The installed CLI isn't on the PATH VS Code captured | Add it as a user or system variable, not just in your PowerShell profile, then restart VS Code |
The connection to Claude Code ended before this message completed | The process ended before acknowledging | Send it again |
Rewind and session saving
| Message | Cause | What to do |
|---|---|---|
Restored the code, but skipped N files | /rewind won't write through links, changed directories or unreadable backups | Turn on /debug to see the paths; undo those files by hand if needed. See Checkpointing |
No files were restored | Backups missing (retention sweep after about 30 days, or a failed copy into a fork) or files unwritable | Ask Claude to reverse the edits or use git. Raise cleanupPeriodDays for the future |
Transcript writes are failing (... ENOSPC) | Saving the transcript is failing | Fix the named condition; the warning clears on the next successful write |
Transcript saving is off with CLAUDE_CODE_SKIP_PROMPT_HISTORY is set | Deliberate opt-out, or inherited by accident | Unset it and restart if unintended |
Transcript saving is off with inherited CLAUDE_CODE_CHILD_SESSION marker | Treated as a nested session | Restart with CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1, and remove the marker from whatever launches you |
Configuration warnings
Most of these print to stderr at startup. In background sessions and JSON output modes they go to the debug log instead (~/.claude/debug/<session-id>.txt, captured with --debug).
| Message | Cause | What to do |
|---|---|---|
Claude Code exited after an unrecoverable interface error | The terminal UI crashed; if during fullscreen start-up, the next launch uses the classic renderer | Restart and claude --resume. See Fullscreen |
Agent descriptions are over the 15.0k-token limit | Your custom subagents' names and descriptions are too long in total | Trim descriptions or delete unused agents |
Not loaded: rename ... a name reserved for the skills synced from your claude.ai account | Something uses anthropic-skills as its name | Rename it and restart |
Ignoring N permissions.allow entries from ... this workspace has not been trusted | Project allow rules need workspace trust | Accept the trust dialog, or set hasTrustDialogAccepted in ~/.claude.json for -p use |
is a network path, which cannot be added as a working directory | UNC, /net automount or a link to a network location | Map a drive and pass it at launch, or mount locally |
Remote managed settings failed to load (<cause>) | Server-managed settings fetch or validation failed; runs on cached policy or none | Check connectivity or sign-in, or ask the admin to fix invalid settings |
Managed settings were not approved; exiting without applying them. | You declined the approval dialog | Restart and approve |
Claude Code can't start: your organization's managed settings block the default model / allows only the models listed in "availableModels" | No allowed model can be the default | Admins: widen availableModels or narrow deniedModels |
Your organization's managed settings allow Claude Code to use: ... | Your provider isn't in allowedProviders | Follow the To continue: steps |
MCP server <name> is blocked by enterprise managed policy | deniedMcpServers, allowedMcpServers, strictPluginOnlyCustomization or disableClaudeAiConnectors | Check your own settings first, then ask the admin |
Managed settings document could not be parsed as a JSON object / drop-in directory could not be read | A deployed managed source is broken; Claude Code fails closed | Admins fix or remove it. See Managed settings |
Unable to read managed policy settings. | A managed source exists but couldn't be read | Admins fix the Detail: cause |
otelHeadersHelper failed; telemetry is not being exported | The helper failed or printed bad output | Make it exit 0 within 30 seconds and print a JSON object of string headers |
headersHelper not run | No saved trust for this folder in -p or SDK mode | Accept trust interactively or set hasTrustDialogAccepted |
Invalid permission rule "..." was skipped: Malformed Tool(content) rule | The rule doesn't end at its closing parenthesis | Rewrite it, for example Bash(ls *). Parentheses inside content are literal |
... is not matched by file permission checks | Write, NotebookEdit, MultiEdit or Glob path rules are never consulted | Use Edit(path) or Read(path) instead |
... has a wildcard before the rest of the command | A rule like Bash(git * main) also approves inserted options such as -c | Put * only after the subcommand, one rule per subcommand. See Permissions |
Denying Bash also turns off the PowerShell tool, so Claude has neither | Windows with Git Bash and a blanket Bash deny | Set CLAUDE_CODE_USE_POWERSHELL_TOOL=1, or use scoped Bash rules |
"crossSessionInbound" must be one of "accept", "hold", "refuse" | Typo in the setting; messages are held meanwhile (refused if in managed settings) | Fix the value |
ANTHROPIC_FOUNDRY_RESOURCE must be a Foundry resource name | A URL or hostname was given | Use the bare name, or set ANTHROPIC_FOUNDRY_BASE_URL instead (not both) |
CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced | Other configuration defeats the cap | Set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 or autoCompactWindow, or update |
[claude-code:unrecognized_model] {...} | Your version doesn't recognise the model ID (written once per model to stderr in -p, debug log otherwise) | Add a modelOverrides entry mapping a real Claude model ID to your alias, update, or fix the typo |
Stale sandbox mask files left by a killed session (in claude doctor) | Zero-byte placeholders left after a killed sandboxed session on Linux or WSL2 | With no other session running in the project, rm each listed file |
A modelOverrides entry for a gateway alias looks like this, with a real model ID as the key and your gateway's name as the value:
{
"modelOverrides": {
"claude-sonnet-4-6": "team-sonnet-prod"
}
}
Responses seem worse than usual
No error, just weaker answers? It's almost always session state rather than a model swap. Claude Code doesn't silently change model versions; the only switches are a configured --fallback-model after an availability error (one turn, with a transcript notice), a Bedrock or Vertex default becoming unavailable, and automatic fallback when a safeguard category has a fallback model (also announced). Check:
- Model:
/model. A leftover choice orANTHROPIC_MODELmay have you on something smaller. - Effort:
/effort. Raise it for hard debugging or design. Defaults differ by model. - Context:
/context. Near full,/compactat a sensible point or/clear. - Stale instructions: oversized
CLAUDE.mdfiles and unused MCP tools crowd the window and steer answers./doctorflags them.
When a reply goes wrong, rewinding beats arguing. Press Esc twice or use /rewind, then re-prompt with more detail; correcting in-thread leaves the bad attempt in context. If something still seems off, /feedback with what you expected sends Anthropic the transcript. If Claude warns about prompt injection in text Claude Code added itself, update and retry, and report it if it persists.
Reporting an error
/feedbacksends your transcript and a description to Anthropic and can open a prefilled GitHub issue. On Bedrock, Vertex, Foundry and other third-party setups, or with no Anthropic credentials, it saves a local archive for your account team instead.claude doctorgives a read-only installation report;/doctorchecks and fixes inside a session.- Check status.claude.com for incidents and search the GitHub issues.