This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 6
66
77Except for [Wrapper and IDE errors](#wrapper-and-ide-errors), which the launching program prints rather than Claude Code itself, these errors and recovery commands apply across the CLI, the [Desktop app](/docs/en/desktop), and [cloud sessions](/docs/en/claude-code-on-the-web), since all three wrap the same Claude Code CLI. For other surface-specific issues, see the troubleshooting section on that surface's page.
88
9<Note>
10 Claude Code calls the Claude API for model responses, so most runtime errors map to an underlying API error code. This page covers what each error means inside Claude Code and how to recover. For the raw HTTP status code definitions, see the [Claude Platform error reference](https://platform.claude.com/docs/en/api/errors).
11</Note>
9> [!NOTE]
10>
11> Claude Code calls the Claude API for model responses, so most runtime errors map to an underlying API error code. This page covers what each error means inside Claude Code and how to recover. For the raw HTTP status code definitions, see the [Claude Platform error reference](https://platform.claude.com/docs/en/api/errors).
1212
1313## Find your error
1414
from line 96
9696| `claude.ai rejected the session token` / `session token rejected` | [Authentication](#claude-ai-rejected-the-session-token) |
9797| `MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)` | [Authentication](#mcp-server-needs-you-to-sign-in-again) |
9898| `rejected the credential from its headersHelper` / `rejected the Authorization header in its config` | [Authentication](#mcp-server-needs-you-to-sign-in-again) |
99| `(check the helper, then start a new task or chat)` / `(update it, then start a new task or chat)` | [Authentication](#mcp-credential-rejected-in-cowork) |
99100| `MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate` | [Authentication](#mcp-server-needs-you-to-sign-in-again) |
100101| `MCP server "<name>" requires re-authorization (token expired)` | [Authentication](#mcp-server-needs-you-to-sign-in-again) |
101102| `This server's URL is missing or not a valid URL, so sign-in can't start` | [Authentication](#mcp-server-url-is-missing-or-not-a-valid-url) |
from line 267
266267| `Custom output styles can't be selected over Remote Control or from a relayed message` | [Command-line errors](#custom-output-styles-cant-be-selected-over-remote-control) |
267268| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [Command-line errors](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |
268269| `/recap only runs when you ask for it yourself in this session` | [Command-line errors](#recap-only-runs-when-you-ask-for-it-yourself) |
270| `/feedback is disabled by your organization's policy`, or the same for `/bug` or `/share` | [Command-line errors](#feedback-is-disabled-by-your-organizations-policy) |
269271| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin errors](#plugin-eval-is-currently-in-early-access) |
270272| `cannot be evaluated where sessions load it` | [Test plugins with evals](/docs/en/plugin-evals#cannot-be-evaluated-where-sessions-load-it) |
271273| `Marketplace "<name>" is registered from an untrusted source` | [Plugin errors](#marketplace-is-registered-from-an-untrusted-source) |
from line 302
300302| `File is covered by a Read deny rule in your permission settings` | [Tool errors](#file-is-covered-by-a-read-deny-rule) |
301303| `cannot contain null bytes (\0)` | [Tool errors](#path-cannot-contain-null-bytes) |
302304| `Path contains null bytes` | [Tool errors](#path-cannot-contain-null-bytes) |
305| `File is too large to read as an image (the limit is 128MB)` | [Tool errors](#file-is-too-large-to-read-as-an-image) |
306| `Cannot read this as an image: <path> is a pipe or a device` | [Tool errors](#file-is-too-large-to-read-as-an-image) |
303307| `subagent_type is required: the general-purpose agent is not available in this session` | [Tool errors](#subagent-type-is-required) |
304308| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [Tool errors](#memory-index-is-over-its-read-limit) |
305309| `pkill: refusing to run` | [Tool errors](#pkill-pattern-matches-the-claude-code-process) |
from line 329
325329| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [Tool errors](#the-source-file-is-not-valid-utf-8-text) |
326330| `the source file has the replacement character U+FFFD` | [Tool errors](#the-source-file-is-not-valid-utf-8-text) |
327331| `Not published: that file is on a network share` | [Tool errors](#not-published-that-file-is-on-a-network-share) |
332| `Not published: Claude sent the same content again after a newer version of the artifact turned it away` / `Not published: Claude sent its changes again over the same file after a newer version of the artifact turned them away` | [Tool errors](#not-published-a-newer-version-of-the-artifact-turned-it-away) |
328333| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [Tool errors](#reading-a-local-file-from-outside-the-connected-folders) |
329334| `cannot read file_path (...) — the file could not be examined, and no one can answer the approval card` | [Tool errors](#reading-a-local-file-from-outside-the-connected-folders) |
330335| `WebFetch cannot fetch localhost or other hostnames without a dot` | [Tool errors](#webfetch-cannot-fetch-localhost) |
from line 355
350355| `Session <id> was stopped while the respawn was in flight` | [Background session errors](#session-was-stopped-while-the-respawn-was-in-flight) |
351356| `This session was running agent '<name>', which is no longer available` | [Background session errors](#session-agent-no-longer-available) |
352357| `This session restarted <time> after its next /loop wakeup was due, so that wakeup will not fire` | [Background session errors](#restarted-after-its-next-loop-wakeup-was-due) |
358| `No LLM gateway: a gateway set in your shell isn't passed to a session opened from another folder` | [Background session errors](#no-llm-gateway-opened-from-another-folder) |
359| `No LLM gateway: opened from another folder · respawn from <folder>` | [Background session errors](#no-llm-gateway-opened-from-another-folder) |
353360| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [Background session errors](#claude_code_process_wrapper-launcher-errors) |
354361| `EUNKNOWN: unknown error, uv_spawn` | [Background session errors](#eunknown-when-starting-a-background-session) |
355362| `EACCES: permission denied, posix_spawn` | [Background session errors](#eacces-when-starting-a-background-session) |
from line 744
737744
738745Most errors in this section mean a quota tied to your account or plan has been reached. Three work differently: [`Server is temporarily limiting requests`](#server-is-temporarily-limiting-requests) is a server-side throttle unrelated to your plan quota, [`Usage credits required for 1M context`](#usage-credits-required-for-1m-context) is an entitlement check rather than an exhausted quota, and [`The prompt to confirm went unanswered`](#the-prompt-to-confirm-went-unanswered) means a usage-credits consent prompt closed unanswered, whether or not a quota was reached.
739746
740<h3 id="youve-hit-your-session-limit">
741 You've hit your session limit
742</h3>
747### You've hit your session limit
743748
744749Subscription plans include a rolling usage allowance. When it runs out you see one of these messages:
745750
from line 850
845850* For Anthropic API keys, see the [rate limits reference](https://platform.claude.com/docs/en/api/rate-limits) for how tiers work and how to set per-workspace caps
846851* Reduce concurrency: lower [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/en/env-vars), avoid running many parallel subagents, or switch to a smaller model with `/model` for high-volume scripted runs
847852
848<h3 id="youve-hit-your-monthly-spend-limit">
849 You've hit your monthly spend limit
850</h3>
853### You've hit your monthly spend limit
851854
852855Your plan's included usage can't cover this request, and the [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) that would otherwise pay for it have reached a spend limit. That happens when one of your plan's usage windows has run out, or when the request is one that only usage credits pay for, such as a request to a model that [bills to usage credits](/docs/en/model-config#fable-and-usage-credits). The message names whose limit blocked you. The text after the `·` says how to get that limit increased, and varies with your plan and whether you manage billing:
853856
from line 876
873876* If the message names a reset time for your plan's window, you can wait for it instead
874877* Run `/usage` to see your plan's windows and when each resets
875878
876<h3 id="spend-limit-reached">
877 Spend limit reached
878</h3>
879### Spend limit reached
879880
880881You connect through a [Claude apps gateway](/docs/en/claude-apps-gateway) and have passed a [spend cap](/docs/en/claude-apps-gateway-spend-limits) your gateway operator set. The gateway blocks your requests until the named period resets or the operator raises the cap. It marks each blocked `429` response `x-should-retry: false`, so Claude Code shows this message without retrying.
881882
from line 1108
11071108* Authenticate with a Console API key instead of your subscription. See [Claude Console authentication](/docs/en/authentication#claude-console-authentication) for setup.
11081109* If you are the admin and do not see an option to enable access, contact [Anthropic support](https://support.claude.com)
11091110
1110<h3 id="routines-are-disabled-by-your-organizations-policy">
1111 Routines are disabled by your organization's policy
1112</h3>
1111### Routines are disabled by your organization's policy
11131112
11141113An Owner in your Team or Enterprise organization has turned off [cloud scheduled tasks](/docs/en/routines), formerly routines, at the organization level. The error appears when you try to create or run one, for example at [claude.ai/code/routines](https://claude.ai/code/routines). On Claude Code v2.1.227 or later, the same setting also [hides `/schedule`](/docs/en/routines#troubleshooting) in the CLI.
11151114
from line 1143
11441143* If the variable isn't set in your shell, check the `env` key in your [settings files](/docs/en/settings#where-settings-live), which applies environment variables to every session
11451144* For this and the other Remote Control startup messages, see [Troubleshoot Remote Control](/docs/en/remote-control#troubleshooting)
11461145
1147<h3 id="remote-control-couldnt-refresh-your-login">
1148 Remote Control couldn't refresh your login
1149</h3>
1146### Remote Control couldn't refresh your login
11501147
11511148Claude Code runs a live [Remote Control](/docs/en/remote-control) connection on short-lived credentials that it obtains and renews using your saved claude.ai login. When claude.ai stops accepting that login, or Claude Code has no saved login left, Claude Code stops Remote Control and needs you to sign in again. Either failure can happen while Claude Code is still connecting or later, when it renews the credentials.
11521149
from line 1178
11811178
11821179Before v2.1.238, Claude Code reported the cases that now say `Signed out of Claude` as `JWT refresh failed: no OAuth token — run /login`, and stopped Remote Control with `Claude.ai login expired — run /login to restore Remote Control` as soon as one login refresh got no answer.
11831180
1184<h3 id="remote-control-could-not-renew-this-computers-connection">
1185 Remote Control could not renew this computer's connection
1186</h3>
1181### Remote Control could not renew this computer's connection
11871182
11881183This warning appears in the terminal running [`claude remote-control`](/docs/en/remote-control#start-a-remote-control-session) when the server can't use your claude.ai login to renew its connection's credential before it expires. The warning's last sentence says how long the current credential still works, or that it has already expired:
11891184
from line 1191
11961191* If the warning tells you to run `claude /login`, open another terminal on the machine running the server, run `claude /login` there, and sign in with your claude.ai account
11971192* If the server still can't sign in once the connection's credential has expired, it prints an error containing `Poll: Authentication failed (401)` and stops. Sign in again as the warning's second sentence says, then run `claude remote-control` again in the terminal where the server stopped.
11981193
1199<h3 id="remote-control-stopped-because-the-signed-in-account-changed">
1200 Remote Control stopped because the signed-in account changed
1201</h3>
1194### Remote Control stopped because the signed-in account changed
12021195
12031196Claude Code shows this line during a [Remote Control](/docs/en/remote-control) session when you sign in to a different claude.ai account or organization on this machine. You made the switch outside the Claude Code session, for example by running `/login` in another terminal.
12041197
from line 1210
12171210
12181211Before v2.1.234, Claude Code didn't notice when you switched to a different account or organization outside the Claude Code session. Claude Code kept the Remote Control session connected until a later request to the Remote Control server failed with `Remote Control server rejected the request (HTTP 404)`. That failure could come hours after the switch.
12191212
1220<h3 id="remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts">
1221 Remote Control stopped because the app running the session signed out or switched accounts
1222</h3>
1213### Remote Control stopped because the app running the session signed out or switched accounts
12231214
12241215When the Claude desktop app or an IDE hosts your session, Claude Code gets its login token from that app rather than from `/login`. When claude.ai rejects that token, Claude Code asks the app for a new one. If the app answers that it's signed out, or that it's now signed in to a different Claude account, Claude Code ends the [Remote Control](/docs/en/remote-control) session and sends the app one of these lines:
12251216
from line 1302
13111302* In non-interactive mode, run `claude` in the same environment, complete `/login`, then rerun your command. For automation that can't sign in interactively, authenticate with `ANTHROPIC_API_KEY` or [generate a long-lived token with `claude setup-token`](/docs/en/authentication#generate-a-long-lived-token).
13121303* If signing in keeps failing, see [Login and authentication](/docs/en/troubleshoot-install#login-and-authentication)
13131304
1314<h3 id="could-not-refresh-your-login">
1315 Could not refresh your login because another Claude Code process is refreshing it
1316</h3>
1305### Could not refresh your login because another Claude Code process is refreshing it
13171306
13181307This message doesn't mean your login was rejected. Your saved claude.ai login had expired and needed renewing. Another Claude Code process on the same machine held the shared refresh lock, or exited and left it behind, and the refresh made no progress while this session waited. Claude Code stops the request before sending it:
13191308
from line 1324
13351324* If the message keeps returning, close other Claude Code windows and processes, then retry.
13361325* If it returns with no other Claude Code process running, run `/login`. Signing in again doesn't wait on the refresh lock.
13371326
1338<h3 id="couldnt-save-your-login">
1339 Couldn't save your login
1340</h3>
1327### Couldn't save your login
13411328
13421329You signed in with claude.ai, but Claude Code couldn't save the login to its credential store, so the login didn't complete. On macOS this can happen when the login keychain locks, for example on sleep or idle, after Claude Code has already read or saved credentials in it during the same session.
13431330
from line 1370
13831370
13841371* Run `/login`, complete the sign-in, then start the session again
13851372
1386<h3 id="artifacts-need-a-claude-ai-login">
1387 Artifacts need a claude.ai login
1388</h3>
1373### Artifacts need a claude.ai login
13891374
13901375Claude Code refused an [artifact](/docs/en/artifacts) publish or read because the session has no claude.ai login it can use for artifacts.
13911376
from line 1388
14031388* When the message says the credential is injected by the session's host environment, you can't change it in that session; start a session that is signed in to claude.ai
14041389* See [Availability](/docs/en/artifacts#availability) for the other requirements artifacts have, such as plan, model provider, and organization policy
14051390
1406<h3 id="administrator-policy-requires-a-cloud-gateway-sign-in">
1407 Administrator policy requires a Cloud gateway sign-in
1408</h3>
1391### Administrator policy requires a Cloud gateway sign-in
14091392
14101393An administrator's [managed settings](/docs/en/managed-settings) on this machine set [`forceLoginMethod`](/docs/en/settings-reference#forceloginmethod) to `"gateway"` or set [`forceLoginGatewayUrl`](/docs/en/settings-reference#forcelogingatewayurl). Unless you select a cloud provider through a variable such as `CLAUDE_CODE_USE_BEDROCK`, Claude Code then accepts only the [Claude apps gateway](/docs/en/claude-apps-gateway) sign-in. You see one of two messages:
14111394
from line 1516
15331516
15341517Update the header value where the server is configured, then reconnect from `/mcp`.
15351518
1536Before v2.1.273, the expired sign-in, `headersHelper`, and `Authorization` header cases all showed `MCP server "<name>" requires re-authorization (token expired)`.
1519In a [Cowork](https://claude.com/docs/cowork/overview) session on your machine in the Claude Desktop app, these messages mean the MCP server rejected a credential it was given. Fix the one the message names, then start a new task or chat in Cowork:
15371520
1521```text theme={null}
1522MCP server "<name>" rejected the credential from its headersHelper (check the helper, then start a new task or chat)
1523MCP server "<name>" rejected the Authorization header in its config (update it, then start a new task or chat)
1524```
1525
1526* **`headersHelper` credential rejected**: check that the helper returns a credential the server accepts, then start a new task or chat in Cowork
1527* **`Authorization` header rejected**: update the `Authorization` value under `headers` in that server's configuration, then start a new task or chat in Cowork
1528
1529Before v2.1.302, a Cowork session showed the `run /mcp to reconnect` endings instead, although `/mcp` isn't available there. If you see such an ending in Cowork, still check the helper or update the header, then start a new task or chat. Before v2.1.273, the expired sign-in, `headersHelper`, and `Authorization` header cases all showed `MCP server "<name>" requires re-authorization (token expired)`.
1530
15381531A server can also refuse a tool call with HTTP 403 `insufficient_scope` to ask you to authorize a scope, sometimes one your token already lists. The message names that scope:
15391532
15401533```text theme={null}
from line 1978
19851978
19861979See [Network access](/docs/en/cloud-environments#network-access) for access levels and the default allowlist. Local CLI sessions are not affected by this policy.
19871980
1988<h3 id="the-proxy-refused-the-connection">
1989 The proxy refused the connection
1990</h3>
1981### The proxy refused the connection
19911982
19921983You see this message when Claude reads an [artifact](/docs/en/artifacts) through the proxy you set in `HTTPS_PROXY` or a related [proxy variable](/docs/en/network-config#environment-variables). Artifact content comes from `*.frame.claudeusercontent.com`, so Claude Code first sends the proxy a `CONNECT` request asking it to open a tunnel to that host. When the proxy refuses, nothing reaches the host, and the message carries the proxy's HTTP status:
19931984
from line 2002
20112002
20122003Before v2.1.238, Claude Code reported a refused tunnel as a generic network error.
20132004
2014<h3 id="the-cloud-environments-service-returned-an-empty-or-unexpected-response">
2015 The cloud environments service returned an empty or unexpected response
2016</h3>
2005### The cloud environments service returned an empty or unexpected response
20172006
20182007Claude Code requests your [cloud environments](/docs/en/cloud-environments) list at several points, such as when you create a cloud session from the CLI or run [`/remote-env`](/docs/en/cloud-environments#select-an-environment-from-the-cli). When it can't read the server's answer, it shows one of these messages:
20192008
from line 2021
20322021
20332022Before v2.1.236, Claude Code showed a raw JavaScript TypeError instead of these messages.
20342023
2035<h3 id="failed-to-fetch-session-from-sessions-api">
2036 Failed to fetch session from Sessions API
2037</h3>
2024### Failed to fetch session from Sessions API
20382025
20392026This message means Claude Code found the [cloud session you asked to pull into your terminal](/docs/en/claude-code-on-the-web#from-cloud-to-terminal) but couldn't read its conversation history from Anthropic's servers, so it didn't open it:
20402027
from line 2037
20502037
20512038Before v2.1.296, Claude Code didn't retry a failed read, and after one it could open the session with an empty conversation and report success instead of printing this message.
20522039
2053<h3 id="couldnt-reconnect-to-your-remote-control-session">
2054 Couldn't reconnect to your Remote Control session
2055</h3>
2040### Couldn't reconnect to your Remote Control session
20562041
20572042```text theme={null}
20582043Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.
from line 2053
20682053
20692054If the server reports instead that the previous session is gone, you don't see this message. Claude Code starts a new session in its place or shows [`Previous session is unavailable — run /remote-control to start a new one`](/docs/en/remote-control#previous-session-is-unavailable).
20702055
2071<h3 id="sessions-ended-while-this-machine-was-offline">
2072 Sessions ended while this machine was offline
2073</h3>
2056### Sessions ended while this machine was offline
20742057
20752058Claude Code shows this message in the terminal running [`claude remote-control`](/docs/en/remote-control#start-a-remote-control-session) after your machine was offline long enough that the server cleaned up the Remote Control environment your machine was serving. The sessions in that environment ended, and you can't resume them. The count is the number of sessions that ended.
20762059
from line 2066
20832066* When Claude Code lists kept worktrees under this message, pick up any uncommitted work from them
20842067* Run `claude remote-control` to start a fresh environment
20852068
2086<h3 id="couldnt-share-the-transcript">
2087 Couldn't share the transcript
2088</h3>
2069### Couldn't share the transcript
20892070
20902071After you agree to share your session transcript from a survey prompt, such as the [session quality survey](/docs/en/data-usage#session-quality-surveys), Claude Code uploads it to Anthropic, or saves a local archive instead on third-party providers, on [Claude apps gateway](/docs/en/claude-apps-gateway) sessions, and when no Anthropic credentials are available. This message means the share didn't complete.
20912072
from line 2081
21002081* Run `/feedback` to send the transcript with a description of what happened. See [Report an error](#report-an-error) if `/feedback` is unavailable in your environment
21012082* If other requests are failing too, check your network connection and see [Unable to connect to API](#unable-to-connect-to-api)
21022083
2103<h3 id="couldnt-send-feedback">
2104 Couldn't send feedback
2105</h3>
2084### Couldn't send feedback
21062085
21072086You sent a report from the [`/feedback`, `/bug`, or `/share` dialog](/docs/en/commands#all-commands) and the upload to Anthropic failed. The dialog keeps your text so you can retry.
21082087
from line 2324
23452324* Configure your gateway to forward the `anthropic-beta` header. See [feature pass-through](/docs/en/llm-gateway-protocol#feature-pass-through) for what gateways must forward.
23462325* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/en/env-vars) before launching. [Disable pre-release capabilities](/docs/en/llm-gateway-protocol#disable-pre-release-capabilities) covers the exact scope.
23472326
2327Before v2.1.302, this error could also name the field `diagnostics` with no gateway involved. It appeared when a session that had already used the Anthropic API moved to Amazon Bedrock or Google Cloud's Agent Platform without a restart. For example, a session you left open moves to Bedrock when you run [`/setup-bedrock`](/docs/en/commands) in another Claude Code window. On those versions, run `/clear` in that session or restart it.
2328
23482329### Tool input schema is invalid
23492330
23502331A tool in the request declared an `input_schema` that fails the API's JSON Schema validation, so the API rejected the whole request. The number after `tools.` is the failing tool's position in the request's tool list, not a name you can look up.
from line 2351
23702351* Remove or [disable](/docs/en/mcp#disable-a-server-without-removing-it) the MCP server that declares the invalid schema. The error names the tool only by position. On v2.1.216 or later, check each server's log for a line naming a tool whose input schema would be rejected. If no log names one, disable servers one at a time.
23712352* If you maintain the server, fix the tool's `input_schema`. The schema must be valid JSON Schema, and top-level property names must be 1 to 64 characters long and use only ASCII letters and digits, `_`, `.`, and `-`. See [Tools with invalid input schemas](/docs/en/mcp#tools-with-invalid-input-schemas).
23722353
2373<h3 id="mcp-tool-name-over-128-characters">
2374 MCP tool name over 128 characters
2375</h3>
2354### MCP tool name over 128 characters
23762355
23772356An MCP server lists a tool whose full name, such as `mcp__<server>__<tool>`, is longer than the 128 characters the API accepts. Claude Code [leaves that tool out of the tools it sends to Claude](/docs/en/mcp#tools-with-names-longer-than-128-characters), and the server's other tools keep working. In a session you start with `claude --debug` from your shell, Claude Code writes this message to the debug log at `~/.claude/debug/<session-id>.txt`:
23782357
from line 2367
23882367
23892368Before v2.1.292, Claude Code sent the tool anyway, and the API rejected every request that included it with `API Error: 400 ... tools.N.custom.name: String should have at most 128 characters`.
23902369
2391<h3 id="tool-use-name-over-200-characters">
2392 tool\_use.name over 200 characters
2393</h3>
2370### tool\_use.name over 200 characters
23942371
23952372A tool call in the conversation history carries a name longer than the 200 characters the API accepts in a request:
23962373
from line 2383
24062383
24072384Before v2.1.281, the overlong name stayed in the history and the API rejected every request that re-sent the conversation, including `/compact` and `--resume`, so this error repeated and the conversation was stuck.
24082385
2409<h3 id="theres-an-issue-with-the-selected-model">
2410 There's an issue with the selected model
2411</h3>
2386### There's an issue with the selected model
24122387
24132388The configured model name was not recognized or your account lacks access to it. As of v2.1.160 the trailing hint, shown here in its interactive form, varies by surface.
24142389
from line 2439
24642439* In the Agent SDK, `setModel()` fails with this message and the session keeps running on its previous model. In the TypeScript SDK, call [`supportedModels()`](/docs/en/agent-sdk/typescript#query-object) to list the models you can switch to.
24652440* Before v2.1.265, `/model` also rejected the `opusplan[1m]` alias spelling with this error. On those versions, update Claude Code, or set the model in [settings](/docs/en/model-config#setting-your-model) or with `--model` instead.
24662441
2467<h3 id="couldnt-confirm-model-with-the-api">
2468 Couldn't confirm model with the API
2469</h3>
2442### Couldn't confirm model with the API
24702443
24712444You switched models through the [Agent SDK](/docs/en/agent-sdk/typescript) `setModel()` method or an app that runs the Claude Code CLI for you, such as the [Desktop app](/docs/en/desktop), and the request that confirms the model ID with your API endpoint got no answer within five seconds. The session keeps its current model.
24722445
from line 2454
24812454* Switch to the model again
24822455* If the switch keeps failing, check that Claude Code can reach your API endpoint; see [Network and connection errors](#network-and-connection-errors)
24832456
2484<h3 id="api-error-model-not-changed">
2485 API error when checking the picked model
2486</h3>
2457### API error when checking the picked model
24872458
24882459You picked a model with `/model <name>`, or an app connected to the session requested the switch. The API refused the minimal request Claude Code sends to verify the model, for a reason that has no entry of its own, such as a rate limit or a server error. The session keeps its current model, and the message ends by saying so:
24892460
from line 2516
25452516* For the per-model wording, you can keep working in the current session by switching to another model: run `/model` in the CLI, call [`setModel()`](/docs/en/agent-sdk/typescript#query-object) on the TypeScript SDK's `Query` object in streaming input mode, or call [`set_model()`](/docs/en/agent-sdk/python#claudesdkclient) on the Python SDK's `ClaudeSDKClient`
25462517* For the organization-policy wording, update before you continue
25472518
2548<h3 id="model-is-restricted-by-your-organizations-settings">
2549 Model is restricted by your organization's settings
2550</h3>
2519### Model is restricted by your organization's settings
25512520
25522521Your organization admin has disabled this model in the claude.ai admin console, or managed settings exclude it through an [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist or a [`deniedModels`](/docs/en/model-config#block-specific-models-or-versions) list. The notice appears at startup when `--model`, `ANTHROPIC_MODEL`, or the `model` setting named the restricted model, and it names the model the session uses instead. If managed settings leave no permitted model for the session to use, see [Managed settings block the default model](#managed-settings-block-the-default-model). The substitution notice can also appear mid-session after an admin disables the model a session is running on in the claude.ai admin console.
25532522
from line 2536
25672536* If the restricted model was set in `--model`, `ANTHROPIC_MODEL`, the `model` field of a settings file, or the `model` frontmatter of a [subagent](/docs/en/sub-agents#choose-a-model), skill, or command, remove or update that value so the notice doesn't recur
25682537* If you need access to the restricted model, ask your organization admin to enable it. See [Organization model restrictions](/docs/en/model-config#organization-model-restrictions).
25692538
2570<h3 id="cant-switch-to-the-default-model">
2571 Can't switch to the default model
2572</h3>
2539### Can't switch to the default model
25732540
25742541You picked the Default model, for example by selecting the Default row in the `/model` picker or typing `/model default`. Claude Code refused the switch, so the session keeps its current model.
25752542
from line 2576
26092576
26102577Before v2.1.260, the managed-plugin refusal read `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`. Claude Code retried the plugin load once and then refused later switches in the session, even when your organization managed no plugins. Restart the session to run the plugin load again on those versions.
26112578
2612<h3 id="couldnt-save-it-as-your-default">
2613 Couldn't save it as your default
2614</h3>
2579### Couldn't save it as your default
26152580
26162581You picked a model to save as your default, for example with `/model <name>` or `Enter` in the `/model` picker, and Claude Code couldn't write the pick to your user settings file, `~/.claude/settings.json`. The switch itself applied, so the current session runs on the model you picked, but your default is unchanged and the next session starts on the old value.
26172582
from line 2629
26642629* If you can't upgrade, run `/model` and select Opus 4.6 or Sonnet 4.6 instead
26652630* If you hit this in the [Agent SDK](/docs/en/agent-sdk/overview), upgrade the SDK package instead. Opus 4.8 needs TypeScript SDK v0.3.154 or later and Python SDK v0.2.88 or later. Sonnet 5 needs TypeScript SDK v0.3.197 or later. Opus 5 needs TypeScript SDK v0.3.219 or later. Opus 5.5 needs TypeScript SDK v0.3.280 or later. Sonnet 5.5 needs TypeScript SDK v0.3.284 or later
26662631
2667<h3 id="effort-isnt-available-with-thinking-turned-off">
2668 Effort isn't available with thinking turned off
2669</h3>
2632### Effort isn't available with thinking turned off
26702633
26712634You turned [extended thinking](/docs/en/model-config#extended-thinking) off and ran at an [effort level](/docs/en/model-config#adjust-effort-level) above `high`. The model doesn't accept that combination, so the API rejected the request.
26722635
from line 2695
27322695* If you are using Opus 4.7 or Opus 4.8, run `claude update` first. Versions before v2.1.156 can trigger this error during normal tool use, and `/rewind` doesn't clear it.
27332696* Run `/rewind`, or press Esc twice, to step back to a checkpoint before the corrupted turn and continue from there. See [Checkpointing](/docs/en/checkpointing) for how checkpoints are created and restored.
27342697
2735<h3 id="invalid-data-in-redacted-thinking-block">
2736 Invalid data in redacted\_thinking block
2737</h3>
2698### Invalid data in redacted\_thinking block
27382699
27392700The API refused the request with a 400 because it couldn't accept a `redacted_thinking` block that an earlier turn in the conversation history carries.
27402701
27412702```text theme={null}
2742API Error: 400 ... Invalid `data` in `redacted_thinking` block
2743```
2744
2745Claude Code leaves the conversation's earlier thinking out of the request and retries once, so the session continues without showing the error. Before v2.1.282, Claude Code kept the refused block, and every later turn failed with the same error.
2746
2747**What to do:**
2748
2749* If you're on v2.1.281 or earlier and every turn fails with this error, run `claude update` and resume the session
2750* If the error persists, run `/clear` to start a conversation that doesn't carry the block
2751
2752### Unsupported tool content removed
2753
2754When Claude Code connects directly to the Anthropic API and loads or previews a saved session, it removes tool content the Anthropic API doesn't accept and leaves this line where removed content sat between two thinking blocks:
2755
2756```text theme={null}
2757[Unsupported tool content removed]
2758```
2759
2760Such content reaches a session file when something other than the Anthropic API answered in the API's format, typically a third-party proxy set through [`ANTHROPIC_BASE_URL`](/docs/en/env-vars) that translates another provider's tool calls. Claude Code removes it only when th
2703API Error: 400 ... Invalid `data` in `redacted_thinkin
No line in this hunk matches that.
