Error reference

Error reference 문서는 Claude Code 공식 문서(errors)를 한국어로 정리한 가이드입니다. Look up Claude Code runtime error messages with what each one means and how to fix it. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Look up Claude Code runtime error messages with what each one means and how to fix it.

한국어 가이드 범위: errors 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Error reference
Find your error
Automatic retries
Server errors
API Error: 500 Internal server error
API Error: Repeated 529 Overloaded errors
Request timed out
The response above may be incomplete
Auto mode cannot determine the safety of an action
Agent terminated early due to an API error
Usage limits
Usage credits required for 1M context
Server is temporarily limiting requests
Request rejected (429)
Credit balance is too low
Could not update your spend limit
Authentication errors
Not logged in
Could not resolve authentication method
Invalid API key
Your apiKeyHelper script is failing
This organization has been disabled
Your organization has disabled API key authentication
Your organization has disabled Claude subscription access
Remote Control requires the Anthropic API
OAuth token revoked or expired
API Error: 401 Invalid authentication credentials
Login expired
OAuth scope requirement
AWS credentials expired or invalid
AWS authentication failed
AWS default-chain credential resolve timed out
Network and connection errors
Unable to connect to API
Socket is closed
Bedrock streaming response has an unexpected content-type
SSL certificate errors
Host not allowed in a cloud session
Request errors
Prompt is too long

상세 내용

Error reference

Find your error

Match the message you see in your terminal to a section below.

Message	Section
`API Error: 500 Internal server error`	Server errors
`API Error: Repeated 529 Overloaded errors`	Server errors
`Request timed out`	Server errors, or Network if the message mentions your internet connection
`Server error mid-response. The response above may be incomplete.`	Server errors
`Connection closed mid-response` / `Response stalled mid-stream`	Server errors
`<model> is temporarily unavailable, so auto mode cannot determine the safety of...`	Server errors
`Auto mode could not evaluate this action and is blocking it for safety`	Server errors
`Auto mode classifier transcript exceeded context window`	Server errors
`Agent terminated early due to an API error`	Server errors
`You've hit your session limit` / `You've hit your weekly limit`	Usage limits
`Usage credits required for 1M context`	Usage limits
`Server is temporarily limiting requests`	Usage limits
`Request rejected (429)`	Usage limits
`Credit balance is too low`	Usage limits
`Could not update your spend limit`	Usage limits
`Not logged in · Please run /login`	Authentication
`Could not resolve authentication method`	Authentication
`Invalid API key`	Authentication
`Your apiKeyHelper script is failing`	Authentication
`This organization has been disabled`	Authentication
`Your organization has disabled API key authentication`	Authentication
`Your organization has disabled Claude subscription access`	Authentication
`Routines are disabled by your organization's policy`	Authentication
`Remote Control is only available when using Claude via api.anthropic.com`	Authentication
`OAuth token revoked` / `OAuth token has expired`	Authentication
`API Error: 401 Invalid authentication credentials`	Authentication
`Login expired · Please run /login`	Authentication
`Failed to authenticate: OAuth session expired and could not be refreshed`	Authentication
`does not meet scope requirement user:profile`	Authentication
`AWS credentials expired or invalid`	Authentication
`AWS authentication failed`	Authentication
`AWS default-chain credential resolve timed out`	Authentication
`Unable to connect to API`	Network
`Socket is closed`	Network
`Waiting for API response · will retry in`	Automatic retries, or Network if it persists
`Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"`	Network
`SSL certificate verification failed`	Network
`SSL certificate error (...)` during login or startup	Network
`403` with `x-deny-reason: host_not_allowed` in a cloud or routine session	Network
`Couldn't reconnect to your Remote Control session`	Network
`Prompt is too long`	Request errors
`Context exceeds the ...-token limit by ... tokens` in `/context` output	Request errors
`Error during compaction: Conversation too long`	Request errors
`Request too large`	Request errors
`Image was too large`	Request errors
`Unable to resize image`	Request errors
`PDF too large` / `PDF is password protected`	Request errors
`Extra inputs are not permitted`	Request errors
`There's an issue with the selected model`	Request errors
`Model ... is not a recognized model id`	Request errors
`Claude Opus is not available with the Claude Pro plan`	Request errors
`Model ... is restricted by your organization's settings`	Request errors
`thinking.type.enabled is not supported for this model`	Request errors
`max_tokens must be greater than thinking.budget_tokens`	Request errors
`API Error: 400 due to tool use concurrency issues`	Request errors
`Claude Code is unable to respond to this request, which appears to violate our Usage Policy`	Request errors
`<model> has safety measures that flagged this message for a cybersecurity topic`	Request errors
`Installation was killed before it could finish (exit code 137)`	Installation errors
`The connection dropped while downloading the update`	Installation errors
`Download timed out: exceeded the total deadline`	Installation errors
`--bg and --print conflict`	Command-line errors
`Error: --json-schema is not a valid JSON Schema`	Command-line errors
`Error: Settings file exceeds the 2MiB limit`	Command-line errors
`Error: Workspace not trusted` when starting Remote Control	Command-line errors
`Could not import <server>: <reason>`	Command-line errors
`Error: MCP tool <name> (passed via --permission-prompt-tool) not found`	Command-line errors
`Input must be provided either through stdin or as a prompt argument when using --print`	Command-line errors
`Diff is too large for ultrareview` / `PR #<N> is too large for ultrareview`	Command-line errors
`Failed to resume the conversation`	Command-line errors
`Marketplace "<name>" is registered from an untrusted source`	Plugin errors
`references ${user_config.*} in a shell-form command`	Plugin errors
`Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command`	Plugin errors
`headersHelper for MCP server '<name>' references ${user_config.*}`	Plugin errors
`would be spawned with zero tools — refusing`	Tool errors
`File is covered by a Read deny rule in your permission settings`	Tool errors
`Error: this write left the memory index at MEMORY.md at ..., over its ... read limit`	Tool errors
`pkill: refusing to run`	Tool errors
`Can't open MCP settings while no terminal is attached to this background session`	Background session errors
{/* max-version: 2.1.212 */}`Can't open MCP settings in a background session`	Background session errors
`This session has no saved transcript`	Background session errors
`This session was running agent '<name>', which is no longer available`	Background session errors
`CLAUDE_CODE_PROCESS_WRAPPER: launcher ...`	Background session errors
`EUNKNOWN: unknown error, uv_spawn`	Background session errors
`Claude Code process exited with code N`	Wrapper and IDE errors
`Restored the code, but skipped N files`	Rewind warnings
`Ignoring N permissions.allow entries from ... this workspace has not been trusted`	Configuration warnings
Responses seem lower quality than usual	Response quality

Automatic retries

Claude Code retries transient failures before showing you an error. Server errors, overloaded responses, request timeouts, temporary 429 throttles, and dropped connections are all retried up to 10 times with exponential backoff. {/* min-version: 2.1.198 /}As of v2.1.198, this covers connections that drop in the middle of a response before any visible output has streamed: Claude Code re-issues the request with the same backoff and the turn continues instead of stopping with a connection error. {/ min-version: 2.1.199 */}As of v2.1.199, temporary 429 throttles that don't carry your plan's quota headers are also retried when you're signed in with a claude.ai subscription; earlier versions retried them only for API key and Enterprise sign-ins.

주요 항목:

{/* min-version: 2.1.199 */}As of v2.1.199, a TLS certificate validation failure, such as a TLS-inspecting proxy, a missing NODE_EXTRA_CA_CERTS bundle, or an expired certificate, fails on the first attempt so the fix appears immediately instead of after the full retry budget. See SSL certificate errors. Transient TLS conditions such as a handshake timeout still retry.
{/* min-version: 2.1.199 */}As of v2.1.199, a server error that arrives after Claude has already streamed visible output keeps the partial response and appends an incomplete-response notice instead of retrying, since re-running the request could execute the same tools twice. Earlier versions discarded the partial output and reported the turn as an error.
{/* min-version: 2.1.208 */}An Amazon Bedrock streaming response with an unexpected content-type fails on the first attempt, because the gateway or proxy rewriting the response would rewrite the retry the same way. Requires Claude Code v2.1.208 or later.

Variable	Default	Effect
`CLAUDE_CODE_MAX_RETRIES`	10	Number of retry attempts. {/* min-version: 2.1.186 /}Capped at 15 as of v2.1.186; {/ min-version: 2.1.199 */}as of v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` raises the default and removes the cap. Lower it to surface failures faster in scripts.
`CLAUDE_CODE_RETRY_WATCHDOG`	unset	Set to `1` in unattended sessions such as CI jobs to retry `429` and `529` capacity errors indefinitely instead of failing after `CLAUDE_CODE_MAX_RETRIES` attempts. {/* min-version: 2.1.199 */}As of v2.1.199 it also raises the default retry count for other transient errors, such as server errors, timeouts, and dropped connections, to 300, roughly three hours of backoff, and removes the cap of 15 on `CLAUDE_CODE_MAX_RETRIES` if you set that variable explicitly.
`API_TIMEOUT_MS`	600000	Per-request timeout in milliseconds. Raise it for slow networks or proxies.

Server errors

Most of these errors come from the inference provider's infrastructure: Anthropic's on the Anthropic API, and that provider's on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or a custom gateway. Auto mode cannot determine the safety of an action and Agent terminated early due to an API error also cover causes on your side, such as an Amazon Bedrock account that can't invoke the classifier model or a subagent that hit a usage limit.

API Error: 500 Internal server error

Claude Code shows the status code and the API's error message for any 5xx response. The example below shows a 500 response on the Anthropic API:

주요 항목:

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

The API is temporarily at capacity across all users. Claude Code has already retried several times before showing this message:

주요 항목:

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.

Request timed out

The API didn't respond before the connection deadline.

주요 항목:

Retry the request
For long-running tasks, break the work into smaller prompts
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

The response above may be incomplete

A streaming response failed after Claude had already produced visible output. Re-sending the request could run the same tool calls twice, so Claude Code keeps what already streamed and appends this notice instead of discarding the turn. Which variant you see names the cause:

주요 항목:

{/* min-version: 2.1.199 */}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 closed mid-response: the connection dropped.
Response stalled mid-stream: the stream stopped sending data.
Read the response that streamed. Nothing has been lost, but the final sentences or tool calls may be missing.
Reply with continue to have Claude pick up where it stopped
If the same error appears before any visible output, Claude Code retries the request instead of finalizing it. See Automatic retries.

Auto mode cannot determine the safety of an action

The model that auto mode uses to classify actions couldn't produce a decision, so auto mode didn't approve the action automatically. The message you see depends on how the classifier failed.

주요 항목:

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
Retry the action; this usually succeeds on the next attempt
Run claude --debug and repeat the action to see the underlying classifier response in the debug log
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
Switch to a different permission mode so you can approve the action when prompted, or start a fresh conversation without the triggering content
Approve or deny the action in the prompt that appears
Run /compact to reduce the conversation size so subsequent actions fit within the classifier window again

More than one failure produces this same message, so the message alone doesn't tell you the cause. When the classifier model is overloaded or rate-limited, the failure is transient and retrying works. On [Amazon Bedrock](/docs/en/amazon-bedrock), including the [Mantle endpoint](/docs/en/amazon-bedrock#use-the-mantle-endpoint), the same message also appears when your AWS account can't invoke the model named in the message, and that failure repeats on every retry until the model is granted.

**What to do:**

* 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](/docs/en/permission-modes#eliminate-prompts-with-auto-mode); 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](/docs/en/amazon-bedrock#iam-configuration) allows invoking it; for Mantle model IDs, [contact your AWS account team](/docs/en/amazon-bedrock#mantle-endpoint-errors)

{/* min-version: 2.1.216 */}When a classifier request fails because your OAuth token expired or was rotated by another session, Claude Code refreshes the token and retries the request once, so a routine token expiry doesn't surface as this message. Before v2.1.216, an expired or rotated token failed each classifier request, and auto mode denied every checked action with this message until the token was refreshed.

When the classifier returned an unparseable response:

**What to do:**

* Retry the action; this usually succeeds on the next attempt
* Run `claude --debug` and repeat the action to see the underlying classifier response in the debug log

When a separate API safety check blocked the classifier request because of earlier conversation content:

**What to do:**

* 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
* Switch to a different [permission mode](/docs/en/permission-modes) so you can approve the action when prompted, or start a fresh conversation without the triggering content

When the conversation has grown larger than the classifier's context window:

Agent terminated early due to an API error

{/* min-version: 2.1.199 */}A subagent's API request failed terminally, for example because a usage limit was reached or retries for a server error ran out, so the subagent stopped before finishing its task. This message requires Claude Code v2.1.199 or later; before then the API error text was returned to Claude as if it were the subagent's result.

주요 항목:

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

Most errors in this section mean a quota tied to your account or plan has been reached. Two work differently: Server is temporarily limiting requests is a server-side throttle unrelated to your plan quota, and Usage credits required for 1M context is an entitlement check rather than an exhausted quota.

주요 항목:

Wait for the reset time shown in the error
For the Opus limit, run /model and switch to another model to keep working
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

The selected model uses the 1M-token extended context window, and your plan only includes it through usage credits.

주요 항목:

Run /model and select the variant without the [1m] suffix to fall back to the standard context window
Run /usage-credits to turn on metered billing for the 1M variant on Pro and Max, or to request it from your admin on Team and Enterprise
If the error persists after /model, a 1M model ID may be set elsewhere. See There's an issue with the selected 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

Server is temporarily limiting requests

The API applied a short-lived throttle that is unrelated to your plan quota.

주요 항목:

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

Request rejected (429)

You have hit the rate limit configured for your API key, Amazon Bedrock project, or Google Cloud project.

주요 항목:

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

Credit balance is too low

Your Console organization has run out of prepaid credits.

주요 항목:

Add credits at platform.claude.com/settings/billing, and consider enabling auto-reload there so the balance refills before it hits zero
Switch to subscription authentication with /login if you have a Pro, Max, Team, or Enterprise plan
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

The server rejected a spend limit change you made from the prompt that appears when you reach your spend limit.

주요 항목:

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

These errors mean Claude Code cannot prove who you are to the API. Run /status at any time to see which credential is currently active.

Not logged in

No valid credential is available for this session.

주요 항목:

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

The session reached the API client without any credential. This appears in background sessions, cloud sessions, and Agent SDK contexts where the interactive login check doesn't run before the first request.

주요 항목:

Upgrade to v2.1.174 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
Run /status in an interactive session in the same environment to confirm which credential source resolves

Invalid API key

The ANTHROPIC_API_KEY environment variable or apiKeyHelper script returned a key the API rejected.

주요 항목:

Check for typos and confirm the key has not been revoked in the Console
Run env | grep ANTHROPIC in the same shell. 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 configured in the apiKeyHelper setting exited with an error, timed out, or printed nothing to stdout. Without a key from the script, the request reaches the API with a placeholder credential, and the API rejects it with 401.

주요 항목:

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 the key to stdout and exits with code 0. See rotate credentials with apiKeyHelper for a working setup.
Run /status to confirm apiKeyHelper is the active credential source. Each time the command fails, its exit code and error output appear in an Authentication panel in the terminal. {/* min-version: 2.1.212 */}Before v2.1.212, the panel was titled Cloud authentication.

This organization has been disabled

A stale ANTHROPIC_API_KEY from a disabled Console organization is overriding your subscription login.

주요 항목:

Unset ANTHROPIC_API_KEY in the current shell and remove it from your shell profile, then relaunch claude
Run /status afterward to confirm the active credential is your subscription
If no environment variable is set and the error persists, the disabled organization is the one tied to your /login. Contact support or sign in with a different account.

Your organization has disabled API key authentication

This message requires Claude Code v2.1.169 or later. Your Console organization's admin has turned off API key authentication, so the API rejects the key Claude Code is sending. The recovery hint after the · varies by where the key came from:

주요 항목:

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 Claude organization doesn't allow signing in to Claude Code with a subscription login. Running /login again with the same account returns the same error.

주요 항목:

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
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

This is a server-side organization setting, so it can't be overridden from local settings, environment variables, or CLI flags.

The Agent SDK and `-p` non-interactive mode surface this as the `oauth_org_not_allowed` error code.

**What to do:**

* 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](/docs/en/authentication#claude-console-authentication) for setup.
* If you are the admin and do not see an option to enable access, contact [Anthropic support](https://support.claude.com)

<h3 id="routines-are-disabled-by-your-organizations-policy">
  Routines are disabled by your organization's policy
</h3>

An Owner in your Team or Enterprise organization has turned off routines at the organization level. The error appears when you try to create or run a routine, including from `/schedule` and the [Routines](/docs/en/routines) UI on claude.ai/code.

Remote Control requires the Anthropic API

The session isn't talking to the Anthropic API directly, so there is no claude.ai backend for Remote Control to pair with.

주요 항목:

Unset ANTHROPIC_BASE_URL and restart the session, or start Remote Control from a session that talks to the Anthropic API directly
For this and the other Remote Control startup messages, see Troubleshoot Remote Control

OAuth token revoked or expired

Your saved login is no longer valid. A revoked token means you signed out everywhere or an admin removed access; an expired token means the automatic refresh failed mid-session.

주요 항목:

Run /login to sign in again
If the error returns within the same session after re-authenticating, run /logout first to fully clear the stored token, then /login
For repeated prompts to log in across launches, see the system clock and macOS Keychain checks in Troubleshooting
For other failures including 403 Forbidden and OAuth browser issues, see Login and authentication

API Error: 401 Invalid authentication credentials

The API recognized the format of your credential but rejected the account or organization behind it. Anthropic returns this message when a credential was recently revoked, when an organization was disabled or removed your access, or when the account itself was deactivated, so an expired token isn't the cause. The credential can be your saved login or an approved ANTHROPIC_API_KEY, and the fix differs, so start by running /status to see which one is active.

주요 항목:

If /status shows an API key row, 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 run unset ANTHROPIC_API_KEY to fall back to your subscription.
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.

Claude Code tried to renew your saved claude.ai or Claude Console login and the OAuth service rejected the stored refresh token, so Claude Code cleared the saved credentials. After that, each request stops locally before it reaches the API, because only /login can create new credentials. {/* min-version: 2.1.206 */}Before v2.1.206, Claude Code sent the request anyway with whatever credential remained in the environment, and every model then failed with There's an issue with the selected model or a 401 instead of a prompt to sign in.

주요 항목:

Run /login to sign in again. Retrying without signing in shows the same message on every request.
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

In [non-interactive mode](/docs/en/headless) (`-p`) and the [Agent SDK](/docs/en/agent-sdk/overview), the message reads as follows, and the structured error code is `authentication_failed`:

OAuth scope requirement

The stored token predates a permission scope that a newer feature needs. You see this most often from /usage and the status line usage indicator:

주요 항목:

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

AWS credentials expired or invalid

{/* min-version: 2.1.198 */}This message requires Claude Code v2.1.198 or later and only appears when awsAuthRefresh is set in your settings file. Your AWS session token expired or was rejected, and the automatic refresh Claude Code already ran didn't produce a credential the API accepts. It appears on a 401 from Claude Platform on AWS or the Mantle endpoint, which is how those providers report an expired security token.

주요 항목:

Run the awsAuthRefresh command named in the message, such as aws sso login --profile myprofile, in another terminal and complete the browser sign-in, then retry
In an interactive session, 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

{/* min-version: 2.1.198 */}This message requires Claude Code v2.1.198 or later and only appears when awsAuthRefresh is set in your settings file. Your AWS provider returned a 403, or Amazon Bedrock returned a 401.

주요 항목:

Run the awsAuthRefresh command named in the message, or aws sso login, in case an expired credential is the cause
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; a stale AWS_PROFILE or default profile is a common cause of a permission mismatch

AWS default-chain credential resolve timed out

The AWS default credential provider chain didn't produce credentials within 60 seconds, so Claude Code stopped the resolve and failed the request. The failure is local credential resolution: the request never reached Amazon Bedrock, Claude Platform on AWS, or the Mantle endpoint. Claude Code clears its credential cache and retries before this error surfaces, so by the time you see it the chain has stalled on repeated attempts.

주요 항목:

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, so the chain resolves from the local SSO cache instead of waiting on a browser flow
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

Network and connection errors

These errors mean a network request from Claude Code failed to reach its destination, or something between Claude Code and the API altered the response on its way back. They usually originate in your local network, proxy, or firewall, or in the cloud environment's network policy.

Unable to connect to API

The TCP connection to the API failed or never completed.

주요 항목:

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
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.

Socket is closed

The connection carrying a streaming response was closed while the response was still arriving, and the failure surfaced with the text Socket is closed. This happens almost exclusively on Windows behind a corporate proxy, when the proxy drops an established tunnel mid-response. Claude Code treats this as a dropped connection and retries it automatically, so the turn continues. Before v2.1.214, the retry didn't cover this failure, and the turn stopped with an error containing 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

Bedrock streaming response has an unexpected content-type

A gateway or proxy between Claude Code and Amazon Bedrock is transforming the streaming response body or its Content-Type header. Amazon Bedrock streams responses as application/vnd.amazon.eventstream, and Claude Code rejects a successful streaming response that reports a different content-type instead of decoding a body it can't read. The request isn't retried.

주요 항목:

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.
If the gateway rewrites only the header and passes the binary body through intact, set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to skip the check until the gateway is fixed. See Streaming errors behind a gateway or proxy.

SSL certificate errors

A proxy or security appliance on your network is intercepting TLS traffic with its own certificate, and Claude Code does not trust it.

주요 항목:

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

{/* min-version: 2.1.199 */}As of v2.1.199, a certificate validation failure isn't retried, so this error appears on the first attempt instead of after the full [retry budget](#automatic-retries). Earlier versions spent a few minutes retrying before showing it. Transient TLS conditions, such as a handshake timeout, still retry.

During `/login` and the startup connectivity check, the same failure is reported with the OpenSSL code and the fix inline:

Host not allowed in a cloud session

An outbound HTTP request from a cloud session or routine was blocked by the environment's network policy.

주요 항목:

Open the routine for editing, or start a cloud session. Select the cloud icon showing your environment's name, such as Default, to open the selector. Hover over your environment and click the settings icon.
In the Update cloud 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.
Run /remote-control to retry the connection
Start Claude Code without --resume to create a new Remote Control session
For other Remote Control startup messages, see Troubleshoot Remote Control

You may also see a TLS certificate that doesn't match the destination's real certificate. The cloud environment routes outbound traffic through a proxy that enforces the network policy, so a mismatched certificate means the proxy terminated the connection, not the destination.

This is not a client-side network problem. Cloud sessions and [routines](/docs/en/routines) run inside a sandboxed environment whose outbound traffic is filtered to the environment's allowlist. The **Default** environment uses **Trusted** access, which permits the [default allowlist](/docs/en/claude-code-on-the-web#default-allowed-domains) of package registries, cloud provider APIs, container registries, and common development domains but blocks everything else.

**What to do:**

* Open the routine for editing, or start a cloud session. Select the cloud icon showing your environment's name, such as **Default**, to open the selector. Hover over your environment and click the settings icon.
* In the **Update cloud 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](/docs/en/claude-code-on-the-web#default-allowed-domains) alongside your custom domains. Select **Full** instead if you want unrestricted access.
* Click **Save changes**. The next run uses the updated allowlist.

See [Network access](/docs/en/claude-code-on-the-web#network-access) for access levels and the default allowlist. Local CLI sessions are not affected by this policy.

<h3 id="couldnt-reconnect-to-your-remote-control-session">
  Couldn't reconnect to your Remote Control session
</h3>

Request errors

These errors relate to the content of your request. Most come back from the API after it rejected the request; a few are produced locally by Claude Code before any request is sent.

Prompt is too long

The conversation plus attached files exceeds the model's context window.

주요 항목:

Run /compact to summarize earlier turns and free space, or /clear to start fresh
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
Subagents inherit every MCP tool definition from the parent session, which can fill their context window before the first turn. Disable MCP servers you are not using before spawning subagents.
Auto-compact is on by default and normally prevents this error. If you have set DISABLE_AUTO_COMPACT, re-enable it or run /compact manually before the window fills.

Context exceeds the token limit

/context shows this warning at the top of its output when the conversation has grown past the model's context window. Requests fail with Prompt is too long until you free space.

주요 항목:

Run /compact to summarize earlier turns and free space, or /clear to start fresh
For more ways to reduce usage, see Prompt is too long

When the limit you exceeded is a compaction window smaller than the model's context window, such as the 200K boundary on 1M-context models, the warning reads differently. Requests still succeed past a compaction window; run the named command to bring usage back under it.

Error during compaction: Conversation too long

/compact itself failed because there is not enough free context to hold the summary it produces.

주요 항목:

Press Esc twice to open the message list and step back several turns. This drops the most recent messages from context. Then run /compact again.
If stepping back doesn't free enough space, run /clear to start a fresh session. Your previous conversation is preserved and can be reopened with /resume.

Request too large

The raw request body exceeded the API's 32MB limit before tokenization, usually because of a large pasted file or attachment.

주요 항목:

Run /compact to summarize the conversation, which drops accumulated images and attachments
Press Esc twice and step back past the turn that added the oversized content
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

A pasted or attached image exceeds the API's size or dimension limits.

주요 항목:

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

Claude Code couldn't downscale an attached image before sending it to the API.

주요 항목:

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 without the image processor.
If the message reports a dimension or size limit, resize or recompress the image below that limit before attaching.

PDF errors

The PDF you attached couldn't be processed. The messages are shown here in their non-interactive form; in an interactive session they instead prompt you to double press esc and try again.

주요 항목:

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

Extra inputs are not permitted

A proxy or LLM gateway between Claude Code and the API stripped the anthropic-beta request header, so the API rejected fields that depend on it.

주요 항목:

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. This disables features that require the beta header so requests succeed through a gateway that cannot forward it.
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 in priority order: the --model flag, the ANTHROPIC_MODEL environment variable, then the model field in .claude/settings.local.json, your project's .claude/settings.json, and ~/.claude/settings.json. Remove the stale value and Claude Code falls back to your account default.
A newly launched model can be available on the Anthropic API before Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry offers it. If you pinned a new model ID on one of those providers and see this error, check your provider's model catalog for availability in your region, and keep the previous version pinned until the new one appears there.
{/* min-version: 2.1.206 */}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.

Claude Code sends beta-only fields such as `context_management`, `effort`, and tool `input_examples` alongside an `anthropic-beta` header that enables them. When a gateway forwards the body but drops the header, the API sees fields it doesn't recognize.

**What to do:**

* 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.
* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/en/env-vars) before launching. This disables features that require the beta header so requests succeed through a gateway that cannot forward it.

<h3 id="theres-an-issue-with-the-selected-model">
  There's an issue with the selected model
</h3>

The 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.

Model is not a recognized model id

The model string you passed to a model switch isn't a model alias, a model ID this Claude Code version knows, or an ID that starts with claude-. The usual causes are a typo in the ID, a display name such as Sonnet 5 where the ID claude-sonnet-5 is expected, or an alias that only newer Claude Code versions recognize. Claude Code rejects the switch immediately. Before v2.1.200, Claude Code saved the string and failed on the next request with There's an issue with the selected model.

주요 항목:

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 a newer Claude Code version supports, run claude update. A full ID that starts with claude- passes this check even when the model is newer than your Claude Code version, so upgrading isn't needed for those.
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 There's an issue with the selected model.
The check runs only on the Anthropic API. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, and behind an LLM gateway or a custom ANTHROPIC_BASE_URL, your provider or gateway defines the model names, so Claude Code accepts any string and passes it through.

Claude Opus is not available with the Claude Pro plan

Your active subscription plan does not include the model you selected.

주요 항목:

Run /model and select a model your plan includes
If you upgraded your plan recently and still see this, run /logout then /login. The stored token reflects your plan at the time you signed in, so upgrading on the web does not take effect in an existing session until you re-authenticate.
See claude.com/pricing for which models each plan includes
Run /model to pick from the models your organization allows. Restricted models are hidden from the picker.
If the restricted model was set in --model, ANTHROPIC_MODEL, or the model field of a settings file, remove or update that value so the notice doesn't recur on each launch
If you need access to the restricted model, ask your organization admin to enable it. See Organization model restrictions.

**What to do:**

* Run `/model` and select a model your plan includes
* If you upgraded your plan recently and still see this, run `/logout` then `/login`. The stored token reflects your plan at the time you signed in, so upgrading on the web does not take effect in an existing session until you re-authenticate.
* See [claude.com/pricing](https://claude.com/pricing) for which models each plan includes

<h3 id="model-is-restricted-by-your-organizations-settings">
  Model is restricted by your organization's settings
</h3>

Your organization admin has disabled this model in the claude.ai admin console, or it is excluded by an [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist in managed settings. When the restricted model was set with `--model`, `ANTHROPIC_MODEL`, or the `model` setting, Claude Code substitutes an allowed model and continues. Typing `/model <name>` for a restricted model is rejected with `Run /model to choose a different model.` and the session keeps its current model.

thinking.type.enabled is not supported for this model

Your Claude Code version is older than the minimum for the selected model. The CLI sent a thinking configuration the model no longer accepts.

주요 항목:

Run claude update and restart Claude Code. Opus 4.7 needs v2.1.111 or later. Opus 4.8 needs v2.1.154 or later. Sonnet 5 needs v2.1.197 or later. Opus 5 needs v2.1.219 or later
If you can't upgrade, run /model and select Opus 4.6 or Sonnet 4.6 instead
{/* min-version: agent-sdk@0.3.219 */}If you hit this in the Agent SDK, 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

실습 체크리스트

공식 문서와 로컬/SDK 버전을 대조합니다.
관련 CLI·SDK 옵션은 공식 페이지와 --help로 교차 확인합니다.
Agent SDK 예시는 TypeScript/Python 패키지 최신 API를 우선합니다.
권한·호스팅·보안 설정 변경 후 통합 테스트를 실행합니다.

자주 쓰는 명령·설정 예시

The trailing sentence names where to check service health and varies by provider. Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry configurations name that provider's service status. A custom `ANTHROPIC_BASE_URL` names the gateway host.

This indicates an unexpected failure inside the API. It is not caused by your prompt, settings, or account.

**What to do:**

* Check [status.claude.com](https://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](#report-an-error) if `/feedback` is unavailable in your environment.

### API Error: Repeated 529 Overloaded errors

The API is temporarily at capacity across all users. Claude Code has already retried several times before showing this message:

The trailing sentence varies by provider in the same way as the 500 error above.

A 529 is not your usage limit and doesn't count against your quota.

**What to do:**

* Check [status.claude.com](https://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`.

### Request timed out

The API didn't respond before the connection deadline.

This can happen during periods of high load or when the model is generating a very large response. The default request timeout is 10 minutes.

**What to do:**

* Retry the request
* For long-running tasks, break the work into smaller prompts
* If a slow network or proxy is the cause, raise `API_TIMEOUT_MS` as described in [Automatic retries](#automatic-retries)
* If timeouts are frequent and your network is otherwise healthy, see [Network and connection errors](#network-and-connection-errors) below

### The response above may be incomplete

A streaming response failed after Claude had already produced visible output. Re-sending the request could run the same tool calls twice, so Claude Code keeps what already streamed and appends this notice instead of discarding the turn. Which variant you see names the cause:

* {/* min-version: 2.1.199 */}`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 closed mid-response`: the connection dropped.
* `Response stalled mid-stream`: the stream stopped sending data.

**What to do:**

* Read the response that streamed. Nothing has been lost, but the final sentences or tool calls may be missing.
* Reply with `continue` to have Claude pick up where it stopped
* If the same error appears before any visible output, Claude Code retries the request instead of finalizing it. See [Automatic retries](#automatic-retries).

### Auto mode cannot determine the safety of an action

The model that [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) uses to classify actions couldn't produce a decision, so auto mode didn't approve the action automatically. The message you see depends on how the classifier failed.

Reads, searches, and edits inside your working directory skip the classifier, so they keep working in all of these cases.

When the classifier model is unavailable:

More than one failure produces this same message, so the message alone doesn't tell you the cause. When the classifier model is overloaded or rate-limited, the failure is transient and retrying works. On [Amazon Bedrock](/docs/en/amazon-bedrock), including the [Mantle endpoint](/docs/en/amazon-bedrock#use-the-mantle-endpoint), the same message also appears when your AWS account can't invoke the model named in the message, and that failure repeats on every retry until the model is granted.

**What to do:**

* 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](/docs/en/permission-modes#eliminate-prompts-with-auto-mode); 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](/docs/en/amazon-bedrock#iam-configuration) allows invoking it; for Mantle model IDs, [contact your AWS account team](/docs/en/amazon-bedrock#mantle-endpoint-errors)

{/* min-version: 2.1.216 */}When a classifier request fails because your OAuth token expired or was rotated by another session, Claude Code refreshes the token and retries the request once, so a routine token expiry doesn't surface as this message. Before v2.1.216, an expired or rotated token failed each classifier request, and auto mode denied every checked action with this message until the token was refreshed.

When the classifier returned an unparseable response:

**What to do:**

* Retry the action; this usually succeeds on the next attempt
* Run `claude --debug` and repeat the action to see the underlying classifier response in the debug log

When a separate API safety check blocked the classifier request because of earlier conversation content:

**What to do:**

* 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
* Switch to a different [permission mode](/docs/en/permission-modes) so you can approve the action when prompted, or start a fresh conversation without the triggering content

When the conversation has grown larger than the classifier's context window:

In an interactive session, auto mode falls back to a normal permission prompt for that action so you can approve or deny it manually. In [non-interactive mode](/docs/en/headless) the run aborts because the transcript only grows and retrying can't succeed.

**What to do:**

* Approve or deny the action in the prompt that appears
* Run `/compact` to reduce the conversation size so subsequent actions fit within the classifier window again

### Agent terminated early due to an API error

{/* min-version: 2.1.199 */}A [subagent](/docs/en/sub-agents)'s API request failed terminally, for example because a usage limit was reached or retries for a server error ran out, so the subagent stopped before finishing its task. This message requires Claude Code v2.1.199 or later; before then the API error text was returned to Claude as if it were the subagent's result.

Error reference

핵심 요약

Look up Claude Code runtime error messages with what each one means and how to fix it.

한국어 가이드 범위: errors 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Error reference
Find your error
Automatic retries
Server errors
API Error: 500 Internal server error
API Error: Repeated 529 Overloaded errors
Request timed out
The response above may be incomplete
Auto mode cannot determine the safety of an action
Agent terminated early due to an API error
Usage limits
Usage credits required for 1M context
Server is temporarily limiting requests
Request rejected (429)
Credit balance is too low
Could not update your spend limit
Authentication errors
Not logged in
Could not resolve authentication method
Invalid API key
Your apiKeyHelper script is failing
This organization has been disabled
Your organization has disabled API key authentication
Your organization has disabled Claude subscription access
Remote Control requires the Anthropic API
OAuth token revoked or expired
API Error: 401 Invalid authentication credentials
Login expired
OAuth scope requirement
AWS credentials expired or invalid
AWS authentication failed
AWS default-chain credential resolve timed out
Network and connection errors
Unable to connect to API
Socket is closed
Bedrock streaming response has an unexpected content-type
SSL certificate errors
Host not allowed in a cloud session
Request errors
Prompt is too long

상세 내용

Error reference

Find your error

Match the message you see in your terminal to a section below.

Message	Section
`API Error: 500 Internal server error`	Server errors
`API Error: Repeated 529 Overloaded errors`	Server errors
`Request timed out`	Server errors, or Network if the message mentions your internet connection
`Server error mid-response. The response above may be incomplete.`	Server errors
`Connection closed mid-response` / `Response stalled mid-stream`	Server errors
`<model> is temporarily unavailable, so auto mode cannot determine the safety of...`	Server errors
`Auto mode could not evaluate this action and is blocking it for safety`	Server errors
`Auto mode classifier transcript exceeded context window`	Server errors
`Agent terminated early due to an API error`	Server errors
`You've hit your session limit` / `You've hit your weekly limit`	Usage limits
`Usage credits required for 1M context`	Usage limits
`Server is temporarily limiting requests`	Usage limits
`Request rejected (429)`	Usage limits
`Credit balance is too low`	Usage limits
`Could not update your spend limit`	Usage limits
`Not logged in · Please run /login`	Authentication
`Could not resolve authentication method`	Authentication
`Invalid API key`	Authentication
`Your apiKeyHelper script is failing`	Authentication
`This organization has been disabled`	Authentication
`Your organization has disabled API key authentication`	Authentication
`Your organization has disabled Claude subscription access`	Authentication
`Routines are disabled by your organization's policy`	Authentication
`Remote Control is only available when using Claude via api.anthropic.com`	Authentication
`OAuth token revoked` / `OAuth token has expired`	Authentication
`API Error: 401 Invalid authentication credentials`	Authentication
`Login expired · Please run /login`	Authentication
`Failed to authenticate: OAuth session expired and could not be refreshed`	Authentication
`does not meet scope requirement user:profile`	Authentication
`AWS credentials expired or invalid`	Authentication
`AWS authentication failed`	Authentication
`AWS default-chain credential resolve timed out`	Authentication
`Unable to connect to API`	Network
`Socket is closed`	Network
`Waiting for API response · will retry in`	Automatic retries, or Network if it persists
`Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"`	Network
`SSL certificate verification failed`	Network
`SSL certificate error (...)` during login or startup	Network
`403` with `x-deny-reason: host_not_allowed` in a cloud or routine session	Network
`Couldn't reconnect to your Remote Control session`	Network
`Prompt is too long`	Request errors
`Context exceeds the ...-token limit by ... tokens` in `/context` output	Request errors
`Error during compaction: Conversation too long`	Request errors
`Request too large`	Request errors
`Image was too large`	Request errors
`Unable to resize image`	Request errors
`PDF too large` / `PDF is password protected`	Request errors
`Extra inputs are not permitted`	Request errors
`There's an issue with the selected model`	Request errors
`Model ... is not a recognized model id`	Request errors
`Claude Opus is not available with the Claude Pro plan`	Request errors
`Model ... is restricted by your organization's settings`	Request errors
`thinking.type.enabled is not supported for this model`	Request errors
`max_tokens must be greater than thinking.budget_tokens`	Request errors
`API Error: 400 due to tool use concurrency issues`	Request errors
`Claude Code is unable to respond to this request, which appears to violate our Usage Policy`	Request errors
`<model> has safety measures that flagged this message for a cybersecurity topic`	Request errors
`Installation was killed before it could finish (exit code 137)`	Installation errors
`The connection dropped while downloading the update`	Installation errors
`Download timed out: exceeded the total deadline`	Installation errors
`--bg and --print conflict`	Command-line errors
`Error: --json-schema is not a valid JSON Schema`	Command-line errors
`Error: Settings file exceeds the 2MiB limit`	Command-line errors
`Error: Workspace not trusted` when starting Remote Control	Command-line errors
`Could not import <server>: <reason>`	Command-line errors
`Error: MCP tool <name> (passed via --permission-prompt-tool) not found`	Command-line errors
`Input must be provided either through stdin or as a prompt argument when using --print`	Command-line errors
`Diff is too large for ultrareview` / `PR #<N> is too large for ultrareview`	Command-line errors
`Failed to resume the conversation`	Command-line errors
`Marketplace "<name>" is registered from an untrusted source`	Plugin errors
`references ${user_config.*} in a shell-form command`	Plugin errors
`Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command`	Plugin errors
`headersHelper for MCP server '<name>' references ${user_config.*}`	Plugin errors
`would be spawned with zero tools — refusing`	Tool errors
`File is covered by a Read deny rule in your permission settings`	Tool errors
`Error: this write left the memory index at MEMORY.md at ..., over its ... read limit`	Tool errors
`pkill: refusing to run`	Tool errors
`Can't open MCP settings while no terminal is attached to this background session`	Background session errors
{/* max-version: 2.1.212 */}`Can't open MCP settings in a background session`	Background session errors
`This session has no saved transcript`	Background session errors
`This session was running agent '<name>', which is no longer available`	Background session errors
`CLAUDE_CODE_PROCESS_WRAPPER: launcher ...`	Background session errors
`EUNKNOWN: unknown error, uv_spawn`	Background session errors
`Claude Code process exited with code N`	Wrapper and IDE errors
`Restored the code, but skipped N files`	Rewind warnings
`Ignoring N permissions.allow entries from ... this workspace has not been trusted`	Configuration warnings
Responses seem lower quality than usual	Response quality

Automatic retries

주요 항목:

{/* min-version: 2.1.199 */}As of v2.1.199, a TLS certificate validation failure, such as a TLS-inspecting proxy, a missing NODE_EXTRA_CA_CERTS bundle, or an expired certificate, fails on the first attempt so the fix appears immediately instead of after the full retry budget. See SSL certificate errors. Transient TLS conditions such as a handshake timeout still retry.
{/* min-version: 2.1.199 */}As of v2.1.199, a server error that arrives after Claude has already streamed visible output keeps the partial response and appends an incomplete-response notice instead of retrying, since re-running the request could execute the same tools twice. Earlier versions discarded the partial output and reported the turn as an error.
{/* min-version: 2.1.208 */}An Amazon Bedrock streaming response with an unexpected content-type fails on the first attempt, because the gateway or proxy rewriting the response would rewrite the retry the same way. Requires Claude Code v2.1.208 or later.

Variable	Default	Effect
`CLAUDE_CODE_MAX_RETRIES`	10	Number of retry attempts. {/* min-version: 2.1.186 /}Capped at 15 as of v2.1.186; {/ min-version: 2.1.199 */}as of v2.1.199 `CLAUDE_CODE_RETRY_WATCHDOG` raises the default and removes the cap. Lower it to surface failures faster in scripts.
`CLAUDE_CODE_RETRY_WATCHDOG`	unset	Set to `1` in unattended sessions such as CI jobs to retry `429` and `529` capacity errors indefinitely instead of failing after `CLAUDE_CODE_MAX_RETRIES` attempts. {/* min-version: 2.1.199 */}As of v2.1.199 it also raises the default retry count for other transient errors, such as server errors, timeouts, and dropped connections, to 300, roughly three hours of backoff, and removes the cap of 15 on `CLAUDE_CODE_MAX_RETRIES` if you set that variable explicitly.
`API_TIMEOUT_MS`	600000	Per-request timeout in milliseconds. Raise it for slow networks or proxies.

Server errors

API Error: 500 Internal server error

Claude Code shows the status code and the API's error message for any 5xx response. The example below shows a 500 response on the Anthropic API:

주요 항목:

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

The API is temporarily at capacity across all users. Claude Code has already retried several times before showing this message:

주요 항목:

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.

Request timed out

The API didn't respond before the connection deadline.

주요 항목:

Retry the request
For long-running tasks, break the work into smaller prompts
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

The response above may be incomplete

주요 항목:

{/* min-version: 2.1.199 */}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 closed mid-response: the connection dropped.
Response stalled mid-stream: the stream stopped sending data.
Read the response that streamed. Nothing has been lost, but the final sentences or tool calls may be missing.
Reply with continue to have Claude pick up where it stopped
If the same error appears before any visible output, Claude Code retries the request instead of finalizing it. See Automatic retries.

Auto mode cannot determine the safety of an action

The model that auto mode uses to classify actions couldn't produce a decision, so auto mode didn't approve the action automatically. The message you see depends on how the classifier failed.

주요 항목:

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
Retry the action; this usually succeeds on the next attempt
Run claude --debug and repeat the action to see the underlying classifier response in the debug log
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
Switch to a different permission mode so you can approve the action when prompted, or start a fresh conversation without the triggering content
Approve or deny the action in the prompt that appears
Run /compact to reduce the conversation size so subsequent actions fit within the classifier window again

More than one failure produces this same message, so the message alone doesn't tell you the cause. When the classifier model is overloaded or rate-limited, the failure is transient and retrying works. On [Amazon Bedrock](/docs/en/amazon-bedrock), including the [Mantle endpoint](/docs/en/amazon-bedrock#use-the-mantle-endpoint), the same message also appears when your AWS account can't invoke the model named in the message, and that failure repeats on every retry until the model is granted.

**What to do:**

* 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](/docs/en/permission-modes#eliminate-prompts-with-auto-mode); 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](/docs/en/amazon-bedrock#iam-configuration) allows invoking it; for Mantle model IDs, [contact your AWS account team](/docs/en/amazon-bedrock#mantle-endpoint-errors)

{/* min-version: 2.1.216 */}When a classifier request fails because your OAuth token expired or was rotated by another session, Claude Code refreshes the token and retries the request once, so a routine token expiry doesn't surface as this message. Before v2.1.216, an expired or rotated token failed each classifier request, and auto mode denied every checked action with this message until the token was refreshed.

When the classifier returned an unparseable response:

**What to do:**

* Retry the action; this usually succeeds on the next attempt
* Run `claude --debug` and repeat the action to see the underlying classifier response in the debug log

When a separate API safety check blocked the classifier request because of earlier conversation content:

**What to do:**

* 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
* Switch to a different [permission mode](/docs/en/permission-modes) so you can approve the action when prompted, or start a fresh conversation without the triggering content

When the conversation has grown larger than the classifier's context window:

Agent terminated early due to an API error

주요 항목:

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

주요 항목:

Wait for the reset time shown in the error
For the Opus limit, run /model and switch to another model to keep working
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

The selected model uses the 1M-token extended context window, and your plan only includes it through usage credits.

주요 항목:

Run /model and select the variant without the [1m] suffix to fall back to the standard context window
Run /usage-credits to turn on metered billing for the 1M variant on Pro and Max, or to request it from your admin on Team and Enterprise
If the error persists after /model, a 1M model ID may be set elsewhere. See There's an issue with the selected 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

Server is temporarily limiting requests

The API applied a short-lived throttle that is unrelated to your plan quota.

주요 항목:

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

Request rejected (429)

You have hit the rate limit configured for your API key, Amazon Bedrock project, or Google Cloud project.

주요 항목:

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

Credit balance is too low

Your Console organization has run out of prepaid credits.

주요 항목:

Add credits at platform.claude.com/settings/billing, and consider enabling auto-reload there so the balance refills before it hits zero
Switch to subscription authentication with /login if you have a Pro, Max, Team, or Enterprise plan
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

The server rejected a spend limit change you made from the prompt that appears when you reach your spend limit.

주요 항목:

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

These errors mean Claude Code cannot prove who you are to the API. Run /status at any time to see which credential is currently active.

Not logged in

No valid credential is available for this session.

주요 항목:

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

주요 항목:

Upgrade to v2.1.174 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
Run /status in an interactive session in the same environment to confirm which credential source resolves

Invalid API key

The ANTHROPIC_API_KEY environment variable or apiKeyHelper script returned a key the API rejected.

주요 항목:

Check for typos and confirm the key has not been revoked in the Console
Run env | grep ANTHROPIC in the same shell. 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

주요 항목:

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 the key to stdout and exits with code 0. See rotate credentials with apiKeyHelper for a working setup.
Run /status to confirm apiKeyHelper is the active credential source. Each time the command fails, its exit code and error output appear in an Authentication panel in the terminal. {/* min-version: 2.1.212 */}Before v2.1.212, the panel was titled Cloud authentication.

This organization has been disabled

A stale ANTHROPIC_API_KEY from a disabled Console organization is overriding your subscription login.

주요 항목:

Unset ANTHROPIC_API_KEY in the current shell and remove it from your shell profile, then relaunch claude
Run /status afterward to confirm the active credential is your subscription
If no environment variable is set and the error persists, the disabled organization is the one tied to your /login. Contact support or sign in with a different account.

Your organization has disabled API key authentication

주요 항목:

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 Claude organization doesn't allow signing in to Claude Code with a subscription login. Running /login again with the same account returns the same error.

주요 항목:

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
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

This is a server-side organization setting, so it can't be overridden from local settings, environment variables, or CLI flags.

The Agent SDK and `-p` non-interactive mode surface this as the `oauth_org_not_allowed` error code.

**What to do:**

* 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](/docs/en/authentication#claude-console-authentication) for setup.
* If you are the admin and do not see an option to enable access, contact [Anthropic support](https://support.claude.com)

<h3 id="routines-are-disabled-by-your-organizations-policy">
  Routines are disabled by your organization's policy
</h3>

An Owner in your Team or Enterprise organization has turned off routines at the organization level. The error appears when you try to create or run a routine, including from `/schedule` and the [Routines](/docs/en/routines) UI on claude.ai/code.

Remote Control requires the Anthropic API

The session isn't talking to the Anthropic API directly, so there is no claude.ai backend for Remote Control to pair with.

주요 항목:

Unset ANTHROPIC_BASE_URL and restart the session, or start Remote Control from a session that talks to the Anthropic API directly
For this and the other Remote Control startup messages, see Troubleshoot Remote Control

OAuth token revoked or expired

Your saved login is no longer valid. A revoked token means you signed out everywhere or an admin removed access; an expired token means the automatic refresh failed mid-session.

주요 항목:

Run /login to sign in again
If the error returns within the same session after re-authenticating, run /logout first to fully clear the stored token, then /login
For repeated prompts to log in across launches, see the system clock and macOS Keychain checks in Troubleshooting
For other failures including 403 Forbidden and OAuth browser issues, see Login and authentication

API Error: 401 Invalid authentication credentials

주요 항목:

If /status shows an API key row, 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 run unset ANTHROPIC_API_KEY to fall back to your subscription.
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.

주요 항목:

Run /login to sign in again. Retrying without signing in shows the same message on every request.
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

In [non-interactive mode](/docs/en/headless) (`-p`) and the [Agent SDK](/docs/en/agent-sdk/overview), the message reads as follows, and the structured error code is `authentication_failed`:

OAuth scope requirement

The stored token predates a permission scope that a newer feature needs. You see this most often from /usage and the status line usage indicator:

주요 항목:

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

AWS credentials expired or invalid

주요 항목:

Run the awsAuthRefresh command named in the message, such as aws sso login --profile myprofile, in another terminal and complete the browser sign-in, then retry
In an interactive session, 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

주요 항목:

Run the awsAuthRefresh command named in the message, or aws sso login, in case an expired credential is the cause
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; a stale AWS_PROFILE or default profile is a common cause of a permission mismatch

AWS default-chain credential resolve timed out

주요 항목:

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, so the chain resolves from the local SSO cache instead of waiting on a browser flow
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

Network and connection errors

Unable to connect to API

The TCP connection to the API failed or never completed.

주요 항목:

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
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.

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

Bedrock streaming response has an unexpected content-type

주요 항목:

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.
If the gateway rewrites only the header and passes the binary body through intact, set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to skip the check until the gateway is fixed. See Streaming errors behind a gateway or proxy.

SSL certificate errors

A proxy or security appliance on your network is intercepting TLS traffic with its own certificate, and Claude Code does not trust it.

주요 항목:

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

{/* min-version: 2.1.199 */}As of v2.1.199, a certificate validation failure isn't retried, so this error appears on the first attempt instead of after the full [retry budget](#automatic-retries). Earlier versions spent a few minutes retrying before showing it. Transient TLS conditions, such as a handshake timeout, still retry.

During `/login` and the startup connectivity check, the same failure is reported with the OpenSSL code and the fix inline:

Host not allowed in a cloud session

An outbound HTTP request from a cloud session or routine was blocked by the environment's network policy.

주요 항목:

Open the routine for editing, or start a cloud session. Select the cloud icon showing your environment's name, such as Default, to open the selector. Hover over your environment and click the settings icon.
In the Update cloud 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.
Run /remote-control to retry the connection
Start Claude Code without --resume to create a new Remote Control session
For other Remote Control startup messages, see Troubleshoot Remote Control

You may also see a TLS certificate that doesn't match the destination's real certificate. The cloud environment routes outbound traffic through a proxy that enforces the network policy, so a mismatched certificate means the proxy terminated the connection, not the destination.

This is not a client-side network problem. Cloud sessions and [routines](/docs/en/routines) run inside a sandboxed environment whose outbound traffic is filtered to the environment's allowlist. The **Default** environment uses **Trusted** access, which permits the [default allowlist](/docs/en/claude-code-on-the-web#default-allowed-domains) of package registries, cloud provider APIs, container registries, and common development domains but blocks everything else.

**What to do:**

* Open the routine for editing, or start a cloud session. Select the cloud icon showing your environment's name, such as **Default**, to open the selector. Hover over your environment and click the settings icon.
* In the **Update cloud 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](/docs/en/claude-code-on-the-web#default-allowed-domains) alongside your custom domains. Select **Full** instead if you want unrestricted access.
* Click **Save changes**. The next run uses the updated allowlist.

See [Network access](/docs/en/claude-code-on-the-web#network-access) for access levels and the default allowlist. Local CLI sessions are not affected by this policy.

<h3 id="couldnt-reconnect-to-your-remote-control-session">
  Couldn't reconnect to your Remote Control session
</h3>

Request errors

These errors relate to the content of your request. Most come back from the API after it rejected the request; a few are produced locally by Claude Code before any request is sent.

Prompt is too long

The conversation plus attached files exceeds the model's context window.

주요 항목:

Run /compact to summarize earlier turns and free space, or /clear to start fresh
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
Subagents inherit every MCP tool definition from the parent session, which can fill their context window before the first turn. Disable MCP servers you are not using before spawning subagents.
Auto-compact is on by default and normally prevents this error. If you have set DISABLE_AUTO_COMPACT, re-enable it or run /compact manually before the window fills.

Context exceeds the token limit

/context shows this warning at the top of its output when the conversation has grown past the model's context window. Requests fail with Prompt is too long until you free space.

주요 항목:

Run /compact to summarize earlier turns and free space, or /clear to start fresh
For more ways to reduce usage, see Prompt is too long

When the limit you exceeded is a compaction window smaller than the model's context window, such as the 200K boundary on 1M-context models, the warning reads differently. Requests still succeed past a compaction window; run the named command to bring usage back under it.

Error during compaction: Conversation too long

/compact itself failed because there is not enough free context to hold the summary it produces.

주요 항목:

Press Esc twice to open the message list and step back several turns. This drops the most recent messages from context. Then run /compact again.
If stepping back doesn't free enough space, run /clear to start a fresh session. Your previous conversation is preserved and can be reopened with /resume.

Request too large

The raw request body exceeded the API's 32MB limit before tokenization, usually because of a large pasted file or attachment.

주요 항목:

Run /compact to summarize the conversation, which drops accumulated images and attachments
Press Esc twice and step back past the turn that added the oversized content
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

A pasted or attached image exceeds the API's size or dimension limits.

주요 항목:

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

Claude Code couldn't downscale an attached image before sending it to the API.

주요 항목:

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 without the image processor.
If the message reports a dimension or size limit, resize or recompress the image below that limit before attaching.

PDF errors

The PDF you attached couldn't be processed. The messages are shown here in their non-interactive form; in an interactive session they instead prompt you to double press esc and try again.

주요 항목:

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

Extra inputs are not permitted

A proxy or LLM gateway between Claude Code and the API stripped the anthropic-beta request header, so the API rejected fields that depend on it.

주요 항목:

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. This disables features that require the beta header so requests succeed through a gateway that cannot forward it.
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 in priority order: the --model flag, the ANTHROPIC_MODEL environment variable, then the model field in .claude/settings.local.json, your project's .claude/settings.json, and ~/.claude/settings.json. Remove the stale value and Claude Code falls back to your account default.
A newly launched model can be available on the Anthropic API before Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry offers it. If you pinned a new model ID on one of those providers and see this error, check your provider's model catalog for availability in your region, and keep the previous version pinned until the new one appears there.
{/* min-version: 2.1.206 */}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.

Claude Code sends beta-only fields such as `context_management`, `effort`, and tool `input_examples` alongside an `anthropic-beta` header that enables them. When a gateway forwards the body but drops the header, the API sees fields it doesn't recognize.

**What to do:**

* 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.
* As a fallback, set [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/en/env-vars) before launching. This disables features that require the beta header so requests succeed through a gateway that cannot forward it.

<h3 id="theres-an-issue-with-the-selected-model">
  There's an issue with the selected model
</h3>

The 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.

Model is not a recognized model id

주요 항목:

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 a newer Claude Code version supports, run claude update. A full ID that starts with claude- passes this check even when the model is newer than your Claude Code version, so upgrading isn't needed for those.
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 There's an issue with the selected model.
The check runs only on the Anthropic API. On Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, and behind an LLM gateway or a custom ANTHROPIC_BASE_URL, your provider or gateway defines the model names, so Claude Code accepts any string and passes it through.

Claude Opus is not available with the Claude Pro plan

Your active subscription plan does not include the model you selected.

주요 항목:

Run /model and select a model your plan includes
If you upgraded your plan recently and still see this, run /logout then /login. The stored token reflects your plan at the time you signed in, so upgrading on the web does not take effect in an existing session until you re-authenticate.
See claude.com/pricing for which models each plan includes
Run /model to pick from the models your organization allows. Restricted models are hidden from the picker.
If the restricted model was set in --model, ANTHROPIC_MODEL, or the model field of a settings file, remove or update that value so the notice doesn't recur on each launch
If you need access to the restricted model, ask your organization admin to enable it. See Organization model restrictions.

**What to do:**

* Run `/model` and select a model your plan includes
* If you upgraded your plan recently and still see this, run `/logout` then `/login`. The stored token reflects your plan at the time you signed in, so upgrading on the web does not take effect in an existing session until you re-authenticate.
* See [claude.com/pricing](https://claude.com/pricing) for which models each plan includes

<h3 id="model-is-restricted-by-your-organizations-settings">
  Model is restricted by your organization's settings
</h3>

Your organization admin has disabled this model in the claude.ai admin console, or it is excluded by an [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist in managed settings. When the restricted model was set with `--model`, `ANTHROPIC_MODEL`, or the `model` setting, Claude Code substitutes an allowed model and continues. Typing `/model <name>` for a restricted model is rejected with `Run /model to choose a different model.` and the session keeps its current model.

thinking.type.enabled is not supported for this model

Your Claude Code version is older than the minimum for the selected model. The CLI sent a thinking configuration the model no longer accepts.

주요 항목:

Run claude update and restart Claude Code. Opus 4.7 needs v2.1.111 or later. Opus 4.8 needs v2.1.154 or later. Sonnet 5 needs v2.1.197 or later. Opus 5 needs v2.1.219 or later
If you can't upgrade, run /model and select Opus 4.6 or Sonnet 4.6 instead
{/* min-version: agent-sdk@0.3.219 */}If you hit this in the Agent SDK, 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

실습 체크리스트

공식 문서와 로컬/SDK 버전을 대조합니다.
관련 CLI·SDK 옵션은 공식 페이지와 --help로 교차 확인합니다.
Agent SDK 예시는 TypeScript/Python 패키지 최신 API를 우선합니다.
권한·호스팅·보안 설정 변경 후 통합 테스트를 실행합니다.

자주 쓰는 명령·설정 예시

The trailing sentence names where to check service health and varies by provider. Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry configurations name that provider's service status. A custom `ANTHROPIC_BASE_URL` names the gateway host.

This indicates an unexpected failure inside the API. It is not caused by your prompt, settings, or account.

**What to do:**

* Check [status.claude.com](https://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](#report-an-error) if `/feedback` is unavailable in your environment.

### API Error: Repeated 529 Overloaded errors

The API is temporarily at capacity across all users. Claude Code has already retried several times before showing this message:

The trailing sentence varies by provider in the same way as the 500 error above.

A 529 is not your usage limit and doesn't count against your quota.

**What to do:**

* Check [status.claude.com](https://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`.

### Request timed out

The API didn't respond before the connection deadline.

This can happen during periods of high load or when the model is generating a very large response. The default request timeout is 10 minutes.

**What to do:**

* Retry the request
* For long-running tasks, break the work into smaller prompts
* If a slow network or proxy is the cause, raise `API_TIMEOUT_MS` as described in [Automatic retries](#automatic-retries)
* If timeouts are frequent and your network is otherwise healthy, see [Network and connection errors](#network-and-connection-errors) below

### The response above may be incomplete

A streaming response failed after Claude had already produced visible output. Re-sending the request could run the same tool calls twice, so Claude Code keeps what already streamed and appends this notice instead of discarding the turn. Which variant you see names the cause:

* {/* min-version: 2.1.199 */}`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 closed mid-response`: the connection dropped.
* `Response stalled mid-stream`: the stream stopped sending data.

**What to do:**

* Read the response that streamed. Nothing has been lost, but the final sentences or tool calls may be missing.
* Reply with `continue` to have Claude pick up where it stopped
* If the same error appears before any visible output, Claude Code retries the request instead of finalizing it. See [Automatic retries](#automatic-retries).

### Auto mode cannot determine the safety of an action

The model that [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) uses to classify actions couldn't produce a decision, so auto mode didn't approve the action automatically. The message you see depends on how the classifier failed.

Reads, searches, and edits inside your working directory skip the classifier, so they keep working in all of these cases.

When the classifier model is unavailable:

More than one failure produces this same message, so the message alone doesn't tell you the cause. When the classifier model is overloaded or rate-limited, the failure is transient and retrying works. On [Amazon Bedrock](/docs/en/amazon-bedrock), including the [Mantle endpoint](/docs/en/amazon-bedrock#use-the-mantle-endpoint), the same message also appears when your AWS account can't invoke the model named in the message, and that failure repeats on every retry until the model is granted.

**What to do:**

* 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](/docs/en/permission-modes#eliminate-prompts-with-auto-mode); 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](/docs/en/amazon-bedrock#iam-configuration) allows invoking it; for Mantle model IDs, [contact your AWS account team](/docs/en/amazon-bedrock#mantle-endpoint-errors)

{/* min-version: 2.1.216 */}When a classifier request fails because your OAuth token expired or was rotated by another session, Claude Code refreshes the token and retries the request once, so a routine token expiry doesn't surface as this message. Before v2.1.216, an expired or rotated token failed each classifier request, and auto mode denied every checked action with this message until the token was refreshed.

When the classifier returned an unparseable response:

**What to do:**

* Retry the action; this usually succeeds on the next attempt
* Run `claude --debug` and repeat the action to see the underlying classifier response in the debug log

When a separate API safety check blocked the classifier request because of earlier conversation content:

**What to do:**

* 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
* Switch to a different [permission mode](/docs/en/permission-modes) so you can approve the action when prompted, or start a fresh conversation without the triggering content

When the conversation has grown larger than the classifier's context window:

In an interactive session, auto mode falls back to a normal permission prompt for that action so you can approve or deny it manually. In [non-interactive mode](/docs/en/headless) the run aborts because the transcript only grows and retrying can't succeed.

**What to do:**

* Approve or deny the action in the prompt that appears
* Run `/compact` to reduce the conversation size so subsequent actions fit within the classifier window again

### Agent terminated early due to an API error

{/* min-version: 2.1.199 */}A [subagent](/docs/en/sub-agents)'s API request failed terminally, for example because a usage limit was reached or retries for a server error ran out, so the subagent stopped before finishing its task. This message requires Claude Code v2.1.199 or later; before then the API error text was returned to Claude as if it were the subagent's result.

Error reference

핵심 요약

문서 구성

상세 내용

Error reference

Find your error

Automatic retries

Server errors

API Error: 500 Internal server error

API Error: Repeated 529 Overloaded errors

Request timed out

The response above may be incomplete

Auto mode cannot determine the safety of an action

Agent terminated early due to an API error

Usage limits

Usage credits required for 1M context

Server is temporarily limiting requests

Request rejected (429)

Credit balance is too low

Could not update your spend limit

Authentication errors

Not logged in

Could not resolve authentication method

Invalid API key

Your apiKeyHelper script is failing

This organization has been disabled

Your organization has disabled API key authentication

Your organization has disabled Claude subscription access

Remote Control requires the Anthropic API

OAuth token revoked or expired

API Error: 401 Invalid authentication credentials

Login expired

OAuth scope requirement

AWS credentials expired or invalid

AWS authentication failed

AWS default-chain credential resolve timed out

Network and connection errors

Unable to connect to API

Socket is closed

Bedrock streaming response has an unexpected content-type

SSL certificate errors

Host not allowed in a cloud session

Request errors

Prompt is too long

Context exceeds the token limit

Error during compaction: Conversation too long

Request too large

Image was too large

Unable to resize image

PDF errors

Extra inputs are not permitted

Model is not a recognized model id

Claude Opus is not available with the Claude Pro plan

thinking.type.enabled is not supported for this model

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Error reference

핵심 요약

문서 구성

상세 내용

Error reference

Find your error

Automatic retries

Server errors

API Error: 500 Internal server error

API Error: Repeated 529 Overloaded errors

Request timed out

The response above may be incomplete

Auto mode cannot determine the safety of an action

Agent terminated early due to an API error

Usage limits

Usage credits required for 1M context

Server is temporarily limiting requests

Request rejected (429)

Credit balance is too low

Could not update your spend limit

Authentication errors

Not logged in