Error reference

​

Find your error

​

Automatic retries

• Server errors, overloaded responses, and request timeouts that arrive before any of Claude’s response has streamed.
• A server error or overloaded response that arrives after Claude has finished thinking but before it has started any text or tool call. Claude Code retries a server error at that point up to two times. Before v2.1.284, Claude Code ended the turn with the error at that point.
• Dropped connections. When a connection drops partway through a request before Claude has completed any part of its response, including its thinking, Claude Code re-issues the request with the same backoff and the turn continues, even if some text had already started streaming. When it drops after Claude has finished thinking but before it has started any text or tool call, Claude Code instead re-issues the request up to two times in quick succession, and ends the turn with Connection lost before a response was produced if the connection keeps dropping at that point.
• A connection that Claude Code detects was broken by your computer going to sleep partway through a request. Claude Code counts it as a dropped connection under the rules above; once the retry label names the specific reason, it reads Connection lost while your computer was asleep, and if the turn ends after Claude has finished thinking but before any text or tool call, the message reads Your computer went to sleep before a response was produced.
• A stalled response stream, when the response headers have arrived but none of Claude’s response has arrived, or when Claude has finished thinking but hasn’t started any text or tool call: Claude Code aborts the stalled connection and re-issues the request at most once, outside the 10-attempt budget above. If the response stalls a second time after Claude has finished thinking but before any text or tool call, Claude Code ends the turn with The response stalled before a response was produced.
• A streaming request the API never answers with response headers, on a connection where the first-byte deadline runs: Claude Code aborts it at the deadline and re-sends it at most once per model request, within the retry budget, then ends the turn with No response from API if that attempt goes unanswered too. On other connections, the request waits out API_TIMEOUT_MS. When you set CLAUDE_CODE_RETRY_WATCHDOG, the one-retry cap doesn’t apply.
• Temporary 429 throttles, but not a gateway’s spend-limit 429, which isn’t a throttle; see Spend limit reached.
  • When you’re signed in with a claude.ai subscription, this includes 429 throttles that don’t carry your plan’s quota headers. Before v2.1.199, Claude Code retried those throttles only for API key and Enterprise sign-ins.
• A request rejected because the input plus max_tokens exceeds the context limit. Re-sending it unchanged would fail the same way, so Claude Code retries with a reduced max_tokens, and stops retrying and compacts instead in two cases:
  • When no reduction can fit, for example when the conversation itself nearly fills the context window.
  • When a retry can’t shrink max_tokens any further. Before v2.1.218, Claude Code could re-send a reduced request that still didn’t fit, such as when the extended thinking budget exceeded the remaining context, until the retry budget ran out.
• An expired or missing Google Cloud credential on Google Cloud’s Agent Platform, or AWS credentials that fail to load on your machine. Claude Code discards its cached credentials and retries up to two times, then reports the error so you can re-authenticate right away, as described under Could not load AWS or Google Cloud credentials. Before v2.1.228, Claude Code retried a failing Google Cloud credential through the full retry budget before showing the error.
• A 401 or 403 from the Anthropic API, directly or through an LLM gateway, while an apiKeyHelper script supplies the credential. Claude Code re-runs the script and retries with its fresh output, within the full retry budget. When the script itself fails on the re-run, Claude Code shows Your apiKeyHelper script is failing instead.

• A TLS certificate validation failure, such as a TLS-inspecting proxy, a missing NODE_EXTRA_CA_CERTS bundle, or an expired certificate. Claude Code reports the error on the first attempt, so you can fix the certificate setup right away; see SSL certificate errors. Claude Code still retries transient TLS conditions such as a handshake timeout. Before v2.1.199, Claude Code retried certificate failures through the full retry budget before showing the error.
• A server error, dropped connection, or stalled stream that arrives after Claude has completed a block of text or a tool call, or has started one after finishing its thinking, but before it finishes the response. Claude Code doesn’t re-run the request, because that could execute the same tool calls twice. It keeps what Claude completed, runs any tool calls Claude finished, and continues the turn from their results. For what you see in an interactive session and in a non-interactive one, read The response above may be incomplete. Before v2.1.199, Claude Code discarded the partial output and reported the whole turn as an error when a server error arrived mid-stream.
• A failure that arrives after Claude has finished the response: nothing needs retrying, so Claude Code keeps the complete response and ends the turn normally.
• An Amazon Bedrock streaming response with an unexpected content-type, because the gateway or proxy rewriting the response would rewrite the retry the same way. Requires Claude Code v2.1.208 or later.
• A non-streaming retry of a failed streaming request that gets a success status but no Claude API message in the body. Claude Code ends the turn with that error.
• A request that your organization’s policy check denied, which surfaces as an API Error: line carrying the denial message. Your organization’s administrators set up the check with Inference hooks, a Claude Enterprise feature, and the message ends with the instructions they configured, or by default tells you to contact them. Claude Code doesn’t re-send the denied request to the same model or to a fallback model, because the denial is about the request’s content rather than the model. Before v2.1.239, Claude Code could re-send a denied request, without streaming or on a configured fallback model, before showing you the denial.
• A response the API’s output content filter blocked. Claude Code shows Output blocked by content filtering policy at once and doesn’t retry or re-send that request.

​

What you see while Claude Code retries or waits

• Before Claude has completed a block of text or a tool call, or started one after finishing its thinking, Claude Code retries the request or ends the turn with an error. Automatic retries says which stalls it retries and how many times.
• After Claude has completed a block of text or a tool call, or started one after finishing its thinking, but before Claude has finished the response, Claude Code keeps what Claude completed, continues the turn from any tool calls Claude finished, and shows The response above may be incomplete. In a non-interactive session, and for a subagent’s response in any session, Claude Code may first prompt Claude to continue the response; that entry says when it does and when you still see the notice there.
• After Claude finished the response, Claude Code ends the turn normally.

​

Tune retry behavior

​

Server errors

​

API Error: 500 Internal server error

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

• Check status.claude.com, or the provider status page named in the message, for active incidents
• Wait a minute, then send your message again. Your original message is still in the conversation, so for a long prompt you can type try again instead of pasting the whole thing.
• If the error persists with no posted incident, run /feedback so Anthropic can investigate with your request details. See Report an error if /feedback is unavailable in your environment.

​

API Error: Repeated 529 Overloaded errors

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

• Check status.claude.com, or the provider status page named in the message, for capacity notices
• Try again in a few minutes
• Run /model and switch to a different model to keep working, since capacity is tracked per model. Claude Code prompts you to do this when one model is under particularly high load, for example Opus is experiencing high load, please use /model to switch to Sonnet. On Fable models the message names Fable. In a session the Claude Desktop app runs, such as the Code tab or Cowork, the message reads Opus is experiencing high load. Switch to Sonnet. and you switch models with the app’s model picker.

​

Request timed out

Request timed out

• Retry the request
• If a slow network or proxy is the cause, raise API_TIMEOUT_MS as described in Automatic retries
• If timeouts are frequent and your network is otherwise healthy, see Network and connection errors below

​

No response from API

API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

• First attempt: CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS when you set it to 1 or more, clamped to between 10 seconds and 30 minutes. Otherwise Claude Code uses the byte-level watchdog timeout listed in Streaming idle watchdogs, so the variables that change that timeout change this wait too. Either way, Claude Code adds one second for every 32KB of request body.
• Retry: one second less than API_TIMEOUT_MS, just under 10 minutes by default, so that the retry can outlast a proxy or gateway that holds the response until generation completes. On Amazon Bedrock, the retry uses the same deadline as the first attempt, and the message shows one duration instead of two.

• Send your message again. Your original message is still in the conversation, so for a long prompt you can type try again instead of pasting the whole thing.
• If it repeats, treat it as a network or proxy problem.
• If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS so the retry waits longer. On Amazon Bedrock, raise CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS as well.
• If the first attempt keeps timing out and the retry then succeeds, raise CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS so the first attempt waits long enough too.

​

The response above may be incomplete

API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection lost mid-response. The response above may be incomplete.
API Error: Your computer went to sleep mid-response. The response above may be incomplete.
API Error: The response stopped arriving. The response above may be incomplete.
API Error: Part of the response never arrived. The response above may be incomplete.
API Error: The response stream was malformed. The response above may be incomplete.

• Server error mid-response: a mid-stream overloaded or 5xx server error. This variant requires Claude Code v2.1.199 or later; before then that case discarded the partial output and reported the whole turn as an error.
• Connection lost mid-response: the connection dropped. You also see this variant when a proxy or gateway ends the response body cleanly before the response has finished.
• Your computer went to sleep mid-response: Claude Code detected that your computer went to sleep while the response was streaming. Once your computer wakes, Claude Code treats the connection as broken and stops reading from it.
• Part of the response never arrived: a stream event was dropped between the API and Claude Code, so a later event referenced content that never arrived. Before v2.1.281, this case ended the turn with API Error: Content block not found.
• The response stream was malformed: an event arrived for a content block that had already finished, or an event arrived damaged. A damaged event is one whose data isn’t valid JSON, whose content is missing, or whose content doesn’t match the event’s type. Before v2.1.284, the parser’s raw error, such as one beginning API Error: JSON Parse error, appeared instead when an event with invalid JSON arrived after Claude had completed its thinking, a block of text, or a tool call.
• The response stopped arriving: the connection stayed open but stopped delivering data, so the streaming idle watchdog aborted it. Before v2.1.222, Claude Code could also report this failure on gateway connections reached through ANTHROPIC_BASE_URL or ANTHROPIC_AWS_BASE_URL while the server’s keep-alive pings were still arriving, because it counted only parsed response events there; upgrading stops those spurious timeouts on those routes. Gateways reached through a provider base URL such as ANTHROPIC_BEDROCK_BASE_URL aren’t wrapped by the byte watchdog; see Streaming idle watchdogs.

• If Claude had completed only its thinking, Claude Code re-issues the request. When the re-issued streams break the same way, the turn ends with Part of the response never arrived and no response was produced. Try again. or The response stream was malformed and no response was produced. Try again.
• If nothing had completed, Claude Code re-sends the request without streaming instead. If you turned that fallback off with CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, the turn ends with API Error: Content block not found for a dropped event or API Error: Content block already closed for a duplicated one. For a damaged event with the fallback off, the turn ends with API Error: Stream event unreadable or the parser’s raw error.

• Earlier in the response, Claude Code either retries the failure or ends the turn with a different error. See Automatic retries.
• When one of these failures arrives after Claude has finished the response, Claude Code keeps the complete response and ends the turn normally, without this notice. Before v2.1.222, Claude Code showed this notice when the connection dropped or stalled after the response finished, and reported the turn as an error even though the response was complete.
• In a non-interactive session, such as a -p run, an Agent SDK run, or a cloud session, you don’t have to send continue yourself when the cut-off response is in the main conversation and contains text but no tool calls: Claude Code keeps the partial output and prompts Claude to continue from where it stopped, up to three times in a row. You see this notice for such a response only once Claude Code has used up those continuations. Before v2.1.246, Claude Code ended a non-interactive turn with this notice on the first cut-off.
• In a subagent, whether the session is interactive or not: when its cut-off response contains text but no tool calls, Claude Code prompts the subagent to continue. The notice becomes the subagent’s last message only once those continuations are used up. Before v2.1.257, a subagent showed this notice on the first cut-off.

• In an interactive session, read the response that remains on screen: Claude Code keeps every block Claude completed before the error, but discards an interrupted final block when the turn ends, so the final sentences or tool calls may be missing. Reply with continue to have Claude pick up from its last completed block.
• In non-interactive mode (-p):
  • With the default text output, Claude Code prints the last completed block of text it still holds from earlier in the turn, followed by this message. When it holds none, Claude Code prints this message alone, for example because Claude Code compacted the conversation mid-turn and cleared that text. Before v2.1.219, Claude Code printed only this message in -p text output and dropped the response it had already produced.
  • With --output-format json or stream-json, Claude Code reports this message in the result field.
  • To continue the turn once the connection is stable, resume the session and send continue as described in Continue conversations.

​

Auto mode cannot determine the safety of an action

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

• Retry after a few seconds; Claude sees the same message and usually retries on its own. A transient failure is unrelated to auto mode eligibility; you don’t need to change settings
• If retries keep failing, continue with read-only tasks and come back to the blocked action later
• On Amazon Bedrock, if the message returns on every retry, check that your account can invoke the model it names: for standard Amazon Bedrock models, confirm your IAM policy allows invoking it; for Mantle model IDs, contact your AWS account team

Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

• Retry the action; this usually succeeds on the next attempt
• Run claude --debug and repeat the action for details in the debug log

Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content — it isn't about the action itself — run with --debug for details

• To a background subagent in a -p run without --input-format stream-json, Claude Code returns an error result containing Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode
• Everywhere else, including interactive sessions and the main conversation of a -p run, Claude Code returns that denial to Claude

• This is not a decision about your action. Content already in your conversation triggered a safety filter on the API when auto mode sent the conversation to the classifier
• Retrying will not help; the same conversation content will trigger the filter again
• In an interactive session, switch to a different permission mode so you can approve the action when prompted
• Start a fresh conversation without the triggering content

Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

• In an interactive session, auto mode falls back to a normal permission prompt for that action so you can approve or deny it manually
• To a background subagent in a non-interactive -p run without --input-format stream-json, Claude Code returns an error result containing Agent aborted: auto mode classifier transcript exceeded context window in headless mode, and the run continues
• Elsewhere in a -p run without a --permission-prompt-tool, there is no prompt to fall back to, so the action doesn’t run and the run continues

• In an interactive session, approve or deny the action in the prompt that appears
• In an interactive session, run /compact to reduce the conversation size so subsequent actions fit within the classifier window again

​

The server returned no safety verdict

The server-side auto mode classifier gave no verdict (timed out), so auto mode cannot determine the safety of <tool>.

Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

• In an interactive session, the message appears as a warning in the transcript and the turn ends
• In a non-interactive -p run, the run ends and reports an execution error. With the default text output, the message prints on stderr.
• When a subagent hit the limit, the subagent stops before finishing, and Claude receives whatever it produced with a note that auto mode stopped it

• Send another message to have Claude try again. The count of responses starts over.
• If the stop repeats and your requests go through an LLM gateway or proxy, check whether it cuts streaming responses short or rewrites them. Server-side classifier review says which gateway behavior causes denials, and the gateway compatibility guide lists what to pass through unchanged.
• Set CLAUDE_CODE_AUTO_MODE_SERVER=0 before you start Claude Code to use its own classifier requests instead. Before v2.1.281, Claude Code didn’t read the variable on a direct connection to the Anthropic API.
• To approve the actions yourself instead, switch out of auto mode

​

Agent terminated early due to an API error

Agent terminated early due to an API error: <error detail>

• Match the error detail after the colon to its own section on this page, such as Usage limits or Server errors, and follow that section’s steps
• Once the underlying error clears, ask Claude to retry the task or resume the subagent

​

Usage limits

​

You’ve hit your session limit

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm

• Wait for the reset time shown in the error
• In the Code tab of the Desktop app, the session-limit card offers an Auto-continue when limits reset checkbox. The weekly-limit card doesn’t. When it’s checked, the Desktop app retries the interrupted turn after the reset and shows the retry time on the card. The Desktop checkbox and the CLI’s Continue automatically at usage limit setting in /config are separate, so turn each off on its own.
• For the Opus or Sonnet limit, run /model and switch to a model outside that family to keep working. Each model has its own prompt cache, so the next request re-reads the whole conversation with no cache hits; see Switching models
• Run /usage to see your plan limits and when they reset
• Run /usage-credits to buy additional usage on Pro and Max, or to request it from your admin on Team and Enterprise. See usage credits for paid plans for how this is billed.
• To upgrade your plan for higher base limits, see claude.com/pricing

​

Usage credits required for 1M context

API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

• Run /model and select the variant without the [1m] suffix to fall back to the standard context window
• Where the message names /usage-credits, run it to turn on metered billing for the 1M variant on Pro and Max, or to request usage credits from your admin on Team and Enterprise. Once usage credits are on, restart Claude Code or start a new session, whichever the message says. Until then, the session stays at the standard context limit.
• If the error persists after /model, a 1M model ID may be set elsewhere. See Setting your model for the configuration locations to check in priority order.
• To remove 1M variants from the model picker entirely, set CLAUDE_CODE_DISABLE_1M_CONTEXT=1

​

The prompt to confirm went unanswered

Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change
Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

• Where the session runs, at the terminal or in the application hosting it, send another prompt and answer the consent prompt when it reappears. For a background session, attach to it from the agents view first. Resending from a Remote Control client shows this message again, because the client can’t display the prompt.
• Run /model to switch to a model that doesn’t bill usage credits
• To give yourself more time, set dialogExpiry to a longer value or "never"

​

Server is temporarily limiting requests

API Error: Server is temporarily limiting requests (not your usage limit)

• Wait briefly and try again
• Check status.claude.com if it persists

​

Request rejected (429)

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

• Run /status and confirm the active credential is the one you expect. A stray ANTHROPIC_API_KEY in your environment can route requests through a low-tier key instead of your subscription.
• Check your provider console for the active limits and request a higher tier if needed
• For Anthropic API keys, see the rate limits reference for how tiers work and how to set per-workspace caps
• Reduce concurrency: lower CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, avoid running many parallel subagents, or switch to a smaller model with /model for high-volume scripted runs

​

You’ve hit your monthly spend limit

You've hit your monthly spend limit · raise it at claude.ai/settings/usage
You've hit your individual spend limit · ask your admin for a higher limit
You've hit your org's monthly spend limit · visit claude.ai/admin-settings/usage to raise it
You've hit your team's shared budget · ask your admin to raise it at claude.ai/admin-settings/usage
You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

• On Pro and Max, increase your monthly spend limit in Settings > Usage on claude.ai, or run /usage-credits
• On Team and Enterprise, increase the limit in Organization settings > Usage if you manage billing, or ask an admin to. /usage-credits sends that request to your admin for you
• For a channel’s limit, ask an org owner or the channel’s manager to raise it on claude.ai. See Per-channel limits in the Claude Tag documentation
• If the message names a reset time for your plan’s window, you can wait for it instead
• Run /usage to see your plan’s windows and when each resets

​

Spend limit reached

spend limit reached (daily; resets 2026-08-09 00:00 UTC)

• Wait for the reset time the message names, or follow the operator’s instructions if the message carries them
• Ask your gateway operator to raise the cap if you hit it routinely

​

Credit balance is too low

Credit balance is too low

• If you have a Pro, Max, Team, or Enterprise plan and see this, run /status and check the API key row. An approved ANTHROPIC_API_KEY in your environment routes requests through that key instead of your subscription. Unset it in the current shell and remove it from your shell profile, then relaunch claude. Run /login if you haven’t signed in with your subscription yet.
• Add credits at platform.claude.com/settings/billing, and consider enabling auto-reload there so the balance refills before it hits zero
• Set per-workspace spend caps in the Console to prevent a single project from draining the org balance. See Manage costs effectively.

​

Could not update your spend limit

Could not update your spend limit: <reason from the server>

• If the message includes a reason, choose a limit that satisfies it, such as a lower amount
• If the message shows only the generic form, retry; the failure may be transient
• If the change keeps failing, make it from your claude.ai billing settings in the browser instead

​

Authentication errors

​

Not logged in

Not logged in · Please run /login

• Run /login to authenticate with your Claude subscription or Console account
• If you expected an environment variable to authenticate you, confirm ANTHROPIC_API_KEY is set and exported in the shell where you launched claude
• For CI or automation where interactive login is not possible, configure an apiKeyHelper script that fetches a key at startup
• See Authentication precedence to understand which credential Claude Code uses when several are present

​

Could not resolve authentication method

Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

• Upgrade to v2.1.176 or later if this appears in a background or cloud session and your credentials are already configured
• Confirm ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, or your cloud provider credentials are set in the environment that launches the worker, not only in your interactive shell
• For the Agent SDK, see authentication setup in the quickstart
• Run /status in an interactive session in the same environment to confirm which credential source resolves

​

Invalid API key

Invalid API key · Fix external API key

• Check for typos and confirm the key has not been revoked in the Console
• In the same shell, run env | grep ANTHROPIC, or in PowerShell Get-ChildItem Env:ANTHROPIC*. Tools like direnv, dotenv shell plugins, and IDE terminals can load a stale key from a .env file in your project without you setting it explicitly.
• Unset ANTHROPIC_API_KEY and run /login to use subscription auth instead
• If the key comes from an apiKeyHelper script, run the script directly to confirm it prints a valid key on stdout
• Run /status to confirm which credential source Claude Code is actually using

​

Your apiKeyHelper script is failing

• The command exited with an error or timed out
• The command printed nothing to stdout
• The command printed something besides the key, such as a login banner or a log line. The panel shows returned output that cannot be used as an API key and says what’s wrong, without repeating the output. Before v2.1.227, Claude Code sent whatever the command printed, after trimming surrounding whitespace.

Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output

• Run the command configured in apiKeyHelper directly in your shell to reproduce the failure
• If the command reports an expired session, re-authenticate with your credential provider, for example by signing in to your SSO or secrets vault again
• Fix the command so it prints only the key to stdout, as a single token of printable ASCII up to 16,384 characters, and exits with code 0. See rotate credentials with apiKeyHelper for a working setup.
• Run /status to see the failure and confirm apiKeyHelper is the active credential source. The apiKeyHelper row shows Failing with the last failure’s detail, such as the exit code and the command’s error output, and disappears after the next successful run. Before v2.1.274, /status showed only the credential source, not the failure.
• Each time the command fails, its exit code and error output also appear in an Authentication panel in the terminal. Before v2.1.212, the panel was titled Cloud authentication.

​

Invalid request header value

Invalid auth token · Fix external auth token
Invalid ANTHROPIC_CUSTOM_HEADERS · Fix the environment variable
Invalid request header from the environment · Fix the environment variable

• Invalid auth token: a bearer token from ANTHROPIC_AUTH_TOKEN or CLAUDE_CODE_OAUTH_TOKEN
• Invalid ANTHROPIC_CUSTOM_HEADERS: a header name or value you set in ANTHROPIC_CUSTOM_HEADERS. The description counts which Name: Value pair is at fault, such as distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS, without repeating the name or value, since you chose both.
• Invalid request header from the environment: a value Claude Code copies into a request header from another environment variable, such as CLAUDE_AGENT_SDK_CLIENT_APP. The description names the variable to fix.

Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

• Re-set the variable or setting the message names, retyping the characters around the reported position rather than pasting from the same source again
• For ANTHROPIC_CUSTOM_HEADERS, keep one Name: Value pair per line and rewrite the pair the message counts
• Run /status to confirm which credential source is active

​

This organization has been disabled

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your subscription instead
Your ANTHROPIC_API_KEY belongs to a disabled organization · Update or unset the environment variable
API Error: 400 ... This organization has been disabled.

• Unset ANTHROPIC_API_KEY in the current shell and remove it from your shell profile, then relaunch claude
• If the message says Update or unset, you have no saved login to fall back to. Unset the key and run /login, or replace the key with one from an active Console organization.
• Run /status afterward to confirm the active credential is your subscription
• If no environment variable is set and the error persists, contact support or sign in with a different account.

​

Your organization has disabled API key authentication

Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead
Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account
Your organization has disabled API key authentication · Sign in again with your claude.ai account

• If the message names ANTHROPIC_API_KEY, unset it in the current shell and remove it from your shell profile or .env file, then relaunch claude
• If the message names apiKeyHelper, remove the apiKeyHelper setting from your settings.json
• Run /login to sign in with your claude.ai account
• Run /status afterward to confirm the active credential is your subscription rather than an API key
• If you need API key authentication for automation, ask your organization admin to re-enable it in the Console

​

Your organization has disabled Claude subscription access

Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

• Ask your admin to enable Claude Code access for your organization
• Authenticate with a Console API key instead of your subscription. See Claude Console authentication for setup.
• If you are the admin and do not see an option to enable access, contact Anthropic support

​

Routines are disabled by your organization’s policy

Routines are disabled by your organization's policy.

• Ask an Owner in your organization to enable the Routines toggle at claude.ai/admin-settings/claude-code
• For one-off scheduled work that does not require organization-level routines, see scheduled tasks

​

Remote Control requires the Anthropic API

Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.

• A CLAUDE_CODE_USE_* provider variable, such as CLAUDE_CODE_USE_BEDROCK for Amazon Bedrock or CLAUDE_CODE_USE_VERTEX for Google Cloud’s Agent Platform
• ANTHROPIC_BASE_URL pointing at a host other than api.anthropic.com, such as an LLM gateway or proxy, even when you sign in with claude.ai; before v2.1.196, a custom base URL didn’t block Remote Control
• ANTHROPIC_UNIX_SOCKET set, so the session sends its requests through a local socket rather than to api.anthropic.com
• An enterprise cloud gateway sign-in made through /login, which doesn’t support Remote Control and has no variable to unset

• Unset the variable the message names, such as CLAUDE_CODE_USE_BEDROCK or ANTHROPIC_BASE_URL, and restart the session, or start Remote Control from a session that talks to the Anthropic API directly
• If the variable isn’t set in your shell, check the env key in your settings files, which applies environment variables to every session
• For this and the other Remote Control startup messages, see Troubleshoot Remote Control

​

Remote Control couldn’t refresh your login

Remote Control disconnected — Claude.ai login expired — run /login to restore Remote Control
Remote Control disconnected — Claude.ai login expired — run /login, then /remote-control
Remote Control disconnected — Claude.ai login was rejected — run /login, then /remote-control
Remote Control disconnected — OAuth token unavailable — run /login to restore Remote Control
Remote Control disconnected — OAuth token refresh failed — run /login to re-authenticate
Remote Control disconnected — JWT refresh failed: no OAuth token — run /login
Remote Control disconnected — Signed out of Claude — run /login, then /remote-control

• Claude.ai login expired and Claude.ai login was rejected: claude.ai no longer accepts your saved login token, because it expired or was revoked
• OAuth token unavailable: Claude Code had no saved login token when the connection’s credential came due for renewal
• OAuth token refresh failed: claude.ai rejected your saved login token while Claude Code was reconnecting, and refreshing the token produced no new one
• JWT refresh failed: no OAuth token: Claude Code found no saved login token to renew with
• Signed out of Claude: you signed out on this machine, for example by running /logout in another terminal, so Claude Code has no saved login left to renew the connection with

• Run /login to sign in again
• Run /remote-control to reconnect the session. Messages ending run /login to restore Remote Control don’t need this step: Claude Code reconnects on its own once you sign in.

​

Remote Control stopped because the signed-in account changed

Remote Control disconnected — signed-in claude.ai account or organization changed on this machine — run /remote-control to start a session for the current account, or /login to switch back, then /remote-control

• Run /remote-control to start a new Remote Control session under the current account or organization
• To switch back, run /login and sign in to the previous account or organization again. Then run /remote-control.

​

Remote Control stopped because the app running the session signed out or switched accounts

Remote Control stopped — the app running this session is now signed in to a different Claude account
Remote Control stopped — the app running this session is signed out of Claude. Sign in there, then turn Remote Control back on

• If the app is signed out, sign in to it again, then turn Remote Control back on in the app
• If the app switched accounts, Claude Code can’t continue the ended session under the new account. Start a new Remote Control session under that account.

​

OAuth token revoked or expired

OAuth token revoked · Please run /login
Please run /login · API Error: 401 OAuth token has expired ...

Failed to authenticate: OAuth token revoked. Please log in again or contact your administrator.
Failed to authenticate. API Error: 401 OAuth token has expired ...

• Run /login at the Claude Code prompt to sign in again
• If your -p command or Agent SDK program uses a saved login, run claude in the same environment, complete /login, then run the command or program again. For automation that can’t sign in interactively, authenticate with ANTHROPIC_API_KEY or generate a long-lived token with claude setup-token.
• If you authenticate with the CLAUDE_CODE_OAUTH_TOKEN environment variable, Claude Code keeps sending the value you set after a request fails with a 401, rather than switching to a stored login’s token. /status shows this credential as an Auth token row reading CLAUDE_CODE_OAUTH_TOKEN. Generate a fresh token with claude setup-token and restart with it, or unset the variable and run /login. Before v2.1.225, Claude Code could replace the variable’s value mid-session with the short-lived access token from a stored login, and the session failed with 401 errors again once that token expired.
• For repeated prompts to log in across launches, see the system clock checks and macOS credential-storage recovery steps in Troubleshooting
• For other failures including 403 Forbidden and OAuth browser issues, see Login and authentication

​

API Error: 401 Invalid authentication credentials

Please run /login · API Error: 401 Invalid authentication credentials

• If /status shows an API key row that isn’t marked as not in use, an approved ANTHROPIC_API_KEY is the active credential and takes precedence over your login, so /login doesn’t replace it. Rotate the key in the Claude Console, or fall back to your subscription by running unset ANTHROPIC_API_KEY, or in PowerShell Remove-Item Env:ANTHROPIC_API_KEY.
• If /status shows only your login, run /login once. If the credential was revoked, a fresh login replaces it.
• If the same message returns for the same login account, the account or organization is no longer active. Check the account and organization that /status reports, and ask your organization admin to restore access.
• If ANTHROPIC_BASE_URL points at an LLM gateway, the text after 401 is your gateway’s message rather than Anthropic’s, and /login doesn’t change it. Fix the credential your gateway expects instead.

​

Login expired

Login expired · Please run /login

Failed to authenticate: OAuth session expired and could not be refreshed

• Run /login to sign in again. Retrying without signing in shows the same message on every request.
• If you sign in with your claude.ai account in another Claude Code window, see Not logged in for when this session starts using that login on its own.
• 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.
• If signing in keeps failing, see Login and authentication

​

Could not refresh your login because another Claude Code process is refreshing it

Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login

Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again

• Try again in a minute. If another process completes the refresh first, this session uses the renewed login.
• If the message keeps returning, close other Claude Code windows and processes, then retry.
• If it returns with no other Claude Code process running, run /login. Signing in again doesn’t wait on the refresh lock.

​

Couldn’t save your login

Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.
Couldn't save your login. Try logging in again.

• On macOS, unlock the login keychain, then run /login again
• On other platforms, run /login again
• If the login still doesn’t save, see Not logged in or token expired for the keychain unlock command and other credential-storage recovery steps

​

Failed to start OAuth callback server

Failed to start OAuth callback server: Failed to start server. Is port 0 in use?

• To sign in right away without the local listener: if you use a claude.ai subscription, run claude setup-token on a machine where sign-in works and set the token it prints as CLAUDE_CODE_OAUTH_TOKEN on this machine. Otherwise set ANTHROPIC_API_KEY to a key from the Claude Console. Authentication precedence explains how Claude Code chooses between credentials.
• To use browser sign-in on this machine instead, Claude Code must be able to listen on 127.0.0.1. If it runs inside a sandbox, check that the sandbox’s policy allows listening on local ports, then run /login again. If it should be able to and still fails, run /feedback so the report includes your environment details.

​

Claude login not accepted

Claude login not accepted · Run /login, then try again

• Run /login, complete the sign-in, then start the session again

​

Artifacts need a claude.ai login

Artifacts need a claude.ai login. Run /login and select "Claude account with subscription", then retry — the "Anthropic Console account" option does not provide claude.ai credentials.

• Run /login and select Claude account with subscription. The Anthropic Console account option doesn’t provide claude.ai credentials.
• When the message names a credential that takes precedence, such as ANTHROPIC_API_KEY, an apiKeyHelper setting, or a Console key saved by a previous /login, remove it the way the message says, then run /login
• When the message says this remote session authenticates through the machine that launched it, sign in to claude.ai on that machine, then reconnect the session
• 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
• See Availability for the other requirements artifacts have, such as plan, model provider, and organization policy

​

Administrator policy requires a Cloud gateway sign-in

Not signed in to the Cloud gateway — run /login.

Administrator policy requires a Cloud gateway sign-in on this machine, but this session is configured with an API key from ANTHROPIC_API_KEY, which a gateway machine does not accept.

To continue: unset ANTHROPIC_API_KEY (or run in a shell without it), then run claude and sign in with /login.

• For Not signed in to the Cloud gateway, run /login and complete the sign-in on the Cloud gateway screen
• For the startup message, remove the credential by following the steps at the end of the message
• If you believe the machine shouldn’t require the gateway, ask the administrator who manages it to remove forceLoginMethod and forceLoginGatewayUrl from its managed settings

​

Your account is on hold

Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted
Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted

• Open the link in the message to view the hold’s details or appeal it
• If you have another Claude account or an API key that isn’t affected by the hold, you can keep working while the hold is resolved: run /login with that account, or set the key with ANTHROPIC_API_KEY

​

Anthropic profile login expired

Anthropic profile login expired · Re-authenticate your Anthropic profile
Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile

• When you set ANTHROPIC_PROFILE explicitly, the message ends with Re-authenticate your Anthropic profile.
• When Claude Code discovered the profile from your configuration directory, the message offers /login, because Claude Code gives a working /login precedence over the discovered profile and then authenticates with your claude.ai or Console account instead. Before v2.1.234, Claude Code showed the Re-authenticate your Anthropic profile form in this case too.

• Sign in to the profile again, then retry: on a machine that offers the keyless sign-in, run /login and choose the Anthropic Console account for a profile the keyless Console sign-in or the Claude Platform CLI’s ant auth login wrote; for other profiles, use the tool that created them
• If an administrator provisioned the profile’s credential, ask them to issue a new one
• Run /status to confirm the active credential source and profile name
• To stop using the profile, unset ANTHROPIC_PROFILE if you set it, then authenticate another way, such as /login or ANTHROPIC_API_KEY

​

OAuth scope requirement

OAuth token does not meet scope requirement: user:profile

• Run /login to get a new token with the current scopes. You don’t need to log out first.

​

claude.ai rejected the session token

claude.ai rejected the session token. Run /login, then reconnect.

• Run /login to sign in again
• Reconnect the connector from /mcp, or run /mcp reconnect <server>. Reconnecting before you sign in again leaves the connector in the same state. The /mcp panel’s Reconnect option reports your claude.ai session token was rejected; the typed /mcp reconnect <server> form reports a successful reconnect even though the token is still rejected.

​

MCP server needs you to sign in again

MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)

MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)

MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)

MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate

​

MCP server URL is missing or not a valid URL

Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.

• Set the entry’s url to the server’s real endpoint where the server is configured, or set the environment variable that its ${VAR} reference names, then run the sign-in again.

​

Issuer mismatch in authorization response

Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

• Try the sign-in again from /mcp
• If the error repeats, report it to the server operator. The fix is server-side: the authorization server must return the same issuer in the iss parameter that it advertises in its metadata
• To connect while the server is being fixed, start Claude Code with MCP_SDK_GENERATION=v1, whose runtime doesn’t run this check. This removes a protection against mix-up attacks, so prefer the server-side fix

​

Refusing to send credentials to non-https token endpoint

Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).

• Serve that token endpoint over HTTPS, for example by putting the server behind a reverse proxy or tunnel that terminates TLS and configuring the server to advertise the https:// address
• To connect without changing the server, start Claude Code with MCP_SDK_GENERATION=v1, whose runtime doesn’t apply this rule and sends the token request over plain HTTP. That choice lasts until you exit and applies to every server. The v1 runtime also skips the issuer check, so prefer serving the endpoint over HTTPS

​

AWS credentials expired or invalid

AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

• If the hint says credentials are managed by this environment, the app that launched Claude Code owns the credential and the other steps here don’t apply: retry, or contact your administrator
• If awsAuthRefresh is set, run the command named in the message, such as aws sso login --profile myprofile, in another terminal and complete the browser sign-in, then retry. Otherwise refresh the AWS credential you use yourself: your SSO sign-in, access keys, API key, or proxy token
• With awsAuthRefresh set in an interactive session, you can instead run /login, choose 3rd-party platform, then select Claude Platform on AWS · refresh credentials under Using 3rd-party platforms to run the same command without restarting Claude Code. See Configure AWS credentials
• If the error repeats after the refresh command succeeds, confirm the identity is valid outside Claude Code with aws sts get-caller-identity in the same shell and profile

​

AWS authentication failed

AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

• If the hint says credentials are managed by this environment, the app that launched Claude Code owns the credential and the other steps here don’t apply: retry, or contact your administrator
• Refresh your AWS credentials in case an expired credential is the cause: run the awsAuthRefresh command named in the message when one is set, or refresh your SSO sign-in, access keys, API key, or proxy token yourself
• If your credentials are current, confirm the IAM permissions in IAM configuration are attached to the identity you’re using and that the selected model is enabled for your account and region
• Run aws sts get-caller-identity to confirm which identity your requests use

​

Google Cloud credentials expired or invalid

Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...

• If the hint says credentials are managed by this environment, the app that launched Claude Code owns the credential and the other steps here don’t apply: retry, or contact your administrator
• If you authenticate with application default credentials, run the gcpAuthRefresh command named in the message, or gcloud auth application-default login, and complete the sign-in, then retry
• If you route through an LLM gateway with CLAUDE_CODE_SKIP_VERTEX_AUTH set, refresh the gateway token in ANTHROPIC_AUTH_TOKEN or ANTHROPIC_CUSTOM_HEADERS, then retry
• If you authenticate with a service account key file, confirm GOOGLE_APPLICATION_CREDENTIALS points at a valid key. See Configure GCP credentials
• If the error repeats after a refresh, confirm the identity works outside Claude Code with gcloud auth application-default print-access-token in the same shell

​

Google Cloud authentication failed

Google Cloud authentication failed · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · if credentials are current, check GCP IAM permissions and Vertex AI model access · API Error: 403 ...

• If the hint says credentials are managed by this environment, the app that launched Claude Code owns the credential and the other steps here don’t apply: retry, or contact your administrator
• Confirm the roles in IAM configuration are granted to the identity you authenticate with
• Confirm the model is enabled for your project. See Request model access

​

Microsoft Foundry authentication failed

Microsoft Foundry authentication failed · refresh your Foundry credential (ANTHROPIC_FOUNDRY_AUTH_TOKEN, ANTHROPIC_FOUNDRY_API_KEY, Azure sign-in for Entra, or your proxy token) and retry · if credentials are current, check access to the Foundry resource · API Error: 401 ...

• If the hint says credentials are managed by this environment, the app that launched Claude Code owns the credential and the other steps here don’t apply: retry, or contact your administrator
• Refresh the credential you configured in Configure Azure credentials: rotate ANTHROPIC_FOUNDRY_API_KEY, mint a fresh ANTHROPIC_FOUNDRY_AUTH_TOKEN, or run az login so the default Microsoft Entra credential chain can sign in again
• If the credential is current, confirm the identity has access to the Foundry resource. See Azure RBAC configuration

​

Could not load AWS or Google Cloud credentials

API Error: Could not load AWS credentials · Could not load credentials from any providers. Check or refresh your AWS credentials and try again.
API Error: Could not load Google Cloud credentials · invalid_grant. Check or refresh your Google Cloud credentials and try again.

• Run your provider’s sign-in command, such as aws sso login --profile myprofile or gcloud auth application-default login, then retry. Bedrock, Agent Platform, or Foundry credentials not loading shows how to confirm the credentials outside Claude Code
• If the detail reads AWS default-chain credential resolve timed out, the chain hung rather than failed, so follow AWS default-chain credential resolve timed out instead

​

AWS default-chain credential resolve timed out

API Error: Could not load AWS credentials · AWS default-chain credential resolve timed out. Check or refresh your AWS credentials and try again.

• Run aws sts get-caller-identity in the same shell with the same AWS_PROFILE. If it also hangs, fix the profile; a credential_process command that prompts interactively is a common cause.
• Complete the sign-in step before starting Claude Code, for example aws sso login --profile myprofile
• If your chain runs an interactive sign-in that legitimately needs more than 60 seconds, such as SSO with MFA through a wrapper like aws-vault, raise the limit in milliseconds with CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS

​

Bedrock setup verification timed out waiting for AWS

Timed out after 60s waiting for AWS. Check your network and proxy settings; if a credential helper needs longer to prompt you, raise CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS.

A request to AWS timed out. Check your network and proxy settings, then try again.

• Run aws sts get-caller-identity in the same shell. If it also hangs, the stall is outside Claude Code, in your network, your proxy, or the credential helper in your AWS profile; fix that first.
• Complete any interactive sign-in before opening the wizard, for example aws sso login --profile myprofile
• If a credential helper in your AWS profile legitimately needs longer than 60 seconds to prompt you, raise the limit in milliseconds with CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS

​

Cloud gateway session expired

Cloud gateway session expired — run /login to reconnect.

Cloud gateway <url> no longer accepts this session. Start `claude` and sign in again with /login.

• Run /login in the session and complete the browser sign-in
• For a non-interactive launch, start claude in the same environment, run /login, then rerun your command

​

Sign-in timed out while waiting for you to continue

Sign-in timed out while waiting for you to continue. Try again.

• Run /login again and confirm the account before the sign-in expires

​

Gateway refused the request

Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ...

• Ask your gateway administrator to look up the request. The API Error: tail carries the refusal the gateway returned
• For administrators: an access control rule on the gateway returns a 403 that the audit log records with its reason, and an upstream’s authorization denial passes through per Upstream error messages

​

Network and connection errors

​

Unable to connect to API

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settings

• Confirm you can reach the API host from the same shell by running curl -I https://api.anthropic.com. On Windows PowerShell use curl.exe -I https://api.anthropic.com so the built-in Invoke-WebRequest alias is not used.
• If you are behind a corporate proxy, set HTTPS_PROXY before launching Claude Code and see Network configuration
• If you route through an LLM gateway or relay, set ANTHROPIC_BASE_URL to its address. See Connect Claude Code to an LLM gateway for setup.
• Ensure your firewall allows the hosts listed in Network access requirements
• Intermittent failures are retried automatically; persistent failures point to a local network issue

• Check whether ANTHROPIC_BASE_URL is set by running echo $ANTHROPIC_BASE_URL, or echo $env:ANTHROPIC_BASE_URL in PowerShell, and look for it in the env block of your settings files. When it’s set, Claude Code sends model requests to that address instead of api.anthropic.com, so a leftover value pointing at a local proxy or gateway that’s no longer running produces Connection refused even though curl reaches the API. Remove it from your shell profile or settings and start Claude Code from a new terminal.
• On Linux and WSL, check /etc/resolv.conf for an unreachable nameserver. WSL in particular can inherit a broken resolver from the host.
• On macOS, a VPN client that was disconnected or uninstalled can leave a tunnel interface or routing rule behind. Check ifconfig for stale utun interfaces and remove the VPN’s network extension in System Settings.
• Docker Desktop and similar container runtimes can intercept outbound traffic. Quit them and retry to rule this out.

​

Unable to connect to Anthropic services

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ECONNREFUSED
Connection to api.anthropic.com timed out after 10 seconds
A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

• If the message names a proxy variable, check that its value points at the right proxy and ask your network team to allow HTTPS connections through it to the host in the message. See Network configuration.
• Work through the checks in Unable to connect to API. The curl test and firewall guidance there apply to this check too.
• If your network is open and the failure persists, Claude Code may not be available in your country

​

Socket is closed

• If you see this error, update to v2.1.214 or later with claude update, then send your message again
• If turns keep failing behind the same proxy after updating, work through Unable to connect to API and check the proxy setup in Network configuration

​

API returned an empty or malformed response

API returned an empty or malformed response (HTTP 200) — check for a proxy or gateway intercepting the request.

• A Response: clause with the content type, the kind of body, such as body is an HTML page or empty body, its size in bytes, and whether the response carried an Anthropic request id. When the response names a recognizable server, such as nginx or cloudflare, or carries intermediary headers, such as cf-ray or via, the clause lists those too.
• A sentence naming the failed streaming request’s id and the failure that triggered the retry. When a stream had opened before the failure, it also reports how many stream events arrived and, if any did, how long the stream had been silent when the attempt failed.

• Read the Response: clause to see which system answered. An HTML body, no Anthropic request id, or a named server such as nginx or cloudflare means that something between Claude Code and the API replied in its place
• If you route through an LLM gateway, test the route with a direct request and fix the hop that returns the non-API response
• On a network with a sign-in page, such as guest Wi-Fi, complete the sign-in in a browser, then retry
• If only the non-streaming route through your gateway is broken, set CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 to turn off this fallback, except when the streaming endpoint itself returns 404, where Claude Code still falls back

​

Streaming response ended before any complete data was received

Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

• Configure any proxy or gateway between Claude Code and your model provider to pass streaming response bodies and their headers through unmodified
• On Amazon Bedrock, see Streaming errors behind a gateway or proxy for the header and body requirements

​

Bedrock streaming response has an unexpected content-type

Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.

• Configure the gateway to pass the InvokeModelWithResponseStream response body and its Content-Type header through unmodified. An intermediary that re-emits the stream as server-sent events is a common cause.
• Setting CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 hides this error, but Claude Code doesn’t decode a binary body under a rewritten header, so those requests fall back to a slower non-streaming path. See Streaming errors behind a gateway or proxy.

​

SSL certificate errors

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

• Export your organization’s CA bundle and point Claude Code at it with NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem
• See Network configuration for full setup instructions
• Don’t set NODE_TLS_REJECT_UNAUTHORIZED=0, which disables certificate validation entirely

​

Host not allowed in a cloud session

HTTP 403
x-deny-reason: host_not_allowed

• Open your environment for editing, either from the routine’s form or from the environment selector where you start cloud sessions.
• In the Edit environment dialog, change Network access from Trusted to Custom, then add the blocked domain to Allowed domains. Enter one domain per line. Check Also include default list of common package managers to keep the default allowlist alongside your custom domains. Select Full instead if you want unrestricted access.
• Click Save changes. The next run uses the updated allowlist. For a cloud session that’s already open, see when a network access change reaches existing sessions.

​

The proxy refused the connection

artifact content fetch failed (proxy refused the connection: HTTP 407)
artifact content fetch failed (proxy refused the connection: HTTP 403)
the proxy refused the connection to the artifact's content host (HTTP 502)

• HTTP 407: the proxy requires credentials it didn’t get. Put them in the proxy URL, as Basic authentication shows.
• HTTP 403: the proxy refuses to tunnel to *.frame.claudeusercontent.com. Ask whoever runs the proxy to allow that host, which Network access requirements lists.
• Any other status, such as HTTP 502: the proxy didn’t open the tunnel for its own reason, such as failing to reach the host. Look the status up in the proxy’s logs.
• unreadable reply in place of a status: whatever is at the proxy address didn’t answer with an HTTP status line. Check that the address is an HTTP proxy.

• Check the address and credentials in the proxy variable, as Proxy configuration describes, then run curl -x http://proxy.example.com:8080 -I https://api.anthropic.com from the shell you start Claude Code in, using your own proxy URL. On Windows PowerShell, run curl.exe. If this probe fails the same way, fix the proxy setup first. If it succeeds, the refusal is specific to the artifact host.
• If your network lets Claude Code reach the artifact host directly, add .frame.claudeusercontent.com to NO_PROXY. Keep the entry that narrow: a broader .claudeusercontent.com entry also bypasses the proxy for bridge.claudeusercontent.com, which organizations with IP allowlisting need to keep on the proxy.

​

The cloud environments service returned an empty or unexpected response

The cloud environments service returned an empty response (HTTP 200 with no body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 with a non-JSON body). This is usually temporary — try again in a moment.
The cloud environments service returned a response in an unexpected format (HTTP 200 without a usable environments list). This is usually temporary — try again in a moment.

• Retry the action. Claude Code requests the list again each time
• If the message keeps appearing, check status.claude.com for active incidents

​

Couldn’t reconnect to your Remote Control session

Couldn't reconnect to your Remote Control session. Retry, or start a fresh session without --resume.

• Run /remote-control to retry the connection
• Start a new session with claude --remote-control to create a new Remote Control session
• For other Remote Control startup messages, see Troubleshoot Remote Control

​

Sessions ended while this machine was offline

2 sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.

• When Claude Code lists kept worktrees under this message, pick up any uncommitted work from them
• Run claude remote-control to start a fresh environment

​

Couldn’t share the transcript

Couldn't share the transcript.

• Run /feedback to send the transcript with a description of what happened. See Report an error if /feedback is unavailable in your environment
• If other requests are failing too, check your network connection and see Unable to connect to API

​

Couldn’t send feedback

Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.

• : not signed in. Run /login, then retry.: the dialog uploads only when Claude Code found Anthropic credentials as it opened, and none were usable by the time you sent. For example, you signed out on this machine in the meantime, or your login could no longer be refreshed.
• A parenthetical: (server returned <status>) is the service’s response code; (request timed out) and (couldn't reach the service) are network failures. When Claude Code can’t name a reason, the parenthetical is absent.

• For the not-signed-in wording, run /login and send again
• Otherwise, send again; if other requests are failing too, check your network connection and see Unable to connect to API
• If it keeps failing, file the report at github.com/anthropics/claude-code/issues, as the message says

​

Request errors

​

Prompt is too long

Prompt is too long

Context limit reached · /compact or /clear to continue

Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on

Prompt is too long · automatic compaction failed: <the underlying error>

• When it can’t summarize any whole exchange, Claude Code keeps your newest prompt word for word and summarizes everything before it.
• In that case, when the conversation doesn’t end with your prompt, Claude Code summarizes the whole conversation instead.

Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).

Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.

• Run /compact to summarize earlier turns and free space, or /clear to start fresh. If /compact answers Not enough messages to compact., the conversation is a single exchange with nothing earlier to summarize, so the space is taken by that one prompt and what Claude Code sends with every request: run /clear and resend with less pasted text or smaller attachments, or reduce the tool definitions and memory files using the steps below
• Run /context to see a breakdown of what is consuming the window: system prompt, tools, memory files, and messages
• Disable MCP servers you are not using with /mcp disable <name> to remove their tool definitions from context
• Trim large CLAUDE.md memory files, or move instructions into path-scoped rules that load only when relevant
• Auto-compact is on by default and normally prevents this error. If you turned it off in /config or with DISABLE_AUTO_COMPACT, turn it back on. If you keep it off, run /compact yourself before the window fills.

​

Context exceeds the token limit

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

• In a multi-turn conversation, run /compact to summarize earlier turns and free space. To start fresh instead, run /clear
• For more ways to reduce usage, see Prompt is too long

​

Request too large

Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.

• Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).: images or documents pushed the request over the limit. Claude Code retries with them stripped.
• Request too large for the API's 32MB request limit: the messages alone are over the limit, so the message says compacting cannot make it fit and Claude Code doesn’t retry. In non-interactive mode, the message tells you to reduce the input or start a new session instead.

• If the message says compacting cannot make it fit, press Esc twice to step back past the turn that added the large content, or run /clear to start fresh
• Otherwise, run /compact, which drops accumulated images and attachments
• Reference large files by path instead of pasting their contents, so Claude can read them in chunks
• For images, see Image was too large below

​

Image was too large

Image was too large. Double press esc to go back and try again with a smaller image.
API Error: 400 ... image dimensions exceed max allowed size

• Resize the image before pasting. The API accepts images up to 8000 pixels on the longest edge for a single image, or 2000 pixels when many images are in context.
• Take a tighter screenshot of the relevant region instead of the full screen

​

Unable to resize image

Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.
Unable to resize image — it is a CMYK JPEG, which Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Re-save it as an RGB PNG or JPEG and try again.
Unable to resize image — it is an animated WebP whose first frame Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. Save its first frame as a PNG or JPEG and try again.
Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.

• If the message asks you to convert the image, convert it to PNG, JPEG, GIF, or WebP and attach it again. Claude Code can verify dimensions for these formats from the file header, without decoding the image.
• If the message reports a dimension or size limit, resize or recompress the image below that limit before attaching.
• If the message names a cause, such as a CMYK JPEG, an animated WebP, or a possibly damaged file, re-save the image in the format the message suggests and attach it again.

​

PDF errors

PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
PDF is password protected. Try using a CLI tool to extract or convert the PDF.
The PDF file was not valid. Try converting it to text first (e.g., pdftotext).

• For oversized PDFs, ask Claude to read a page range with the Read tool instead of attaching the whole file, or extract text with a tool like pdftotext and reference the output file by path
• For protected or invalid PDFs, remove the password or re-export the file from its source application, then try again

pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.

​

Extra inputs are not permitted

API Error: 400 ... Extra inputs are not permitted ... context_management

• Configure your gateway to forward the anthropic-beta header. See feature pass-through for what gateways must forward.
• As a fallback, set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 before launching. Disable pre-release capabilities covers the exact scope.

​

Tool input schema is invalid

API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'

• If your Claude Code version is earlier than v2.1.216, run claude update.
• Remove or disable 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.
• 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.

​

tool_use.name over 200 characters

API Error: 400 ... tool_use.name: String should have at most 200 characters

• Run claude update, then resume the conversation. The updated version repairs the overlong name when it loads the transcript, so a conversation that was stuck works again.

​

There’s an issue with the selected model

There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.

• Interactive CLI: run /model to pick from models available to your account.
• Non-interactive mode (-p): pass --model with a valid alias or ID, or set ANTHROPIC_MODEL. The error text shows Run --model on this surface.
• Agent SDK: the error text omits the hint because the model is set programmatically. Set model on Options in TypeScript or ClaudeAgentOptions(model=...) in Python, and handle the structured model_not_found error to surface your own retry or model picker.
• Use an alias such as sonnet or opus instead of a full versioned ID. Aliases resolve to a maintained default so they don’t go stale. See Model configuration.
• If the wrong model keeps coming back in the CLI, a stale ID is set somewhere. Check the places you can set a model in priority order and remove the stale value.
• Claude Code reports an expired claude.ai login as Login expired, not as this error. Before v2.1.206, an expired login that could no longer be refreshed failed every model with this error; run /login if you see that on an older version.
• For Google Cloud’s Agent Platform deployments, see Google Cloud’s Agent Platform troubleshooting.

​

Model is not a recognized model id

Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

• Run /model with no argument to open the picker and choose from the models available to your account, then pass the alias or ID shown there
• If you used an alias that only a newer Claude Code version supports, run claude update, or pass the model’s full ID instead. The server can still require a minimum Claude Code version for that model; see Claude Code does not support this model.
• A model saved before v2.1.200 isn’t repaired by this check. If a stale value keeps coming back, remove it from the locations listed under Setting your model.
• On any provider other than the Anthropic API, or behind a gateway or custom ANTHROPIC_BASE_URL, only an empty string gets this error. Claude Code can still write the unrecognized-model diagnostic line at request time, on every provider.

​

Model not found

Model 'claude-opus-9' not found