错误参考¶

查阅 Claude Code 运行时错误消息的含义和修复方法。

本页列出 Claude Code 显示的运行时错误及恢复方式。 安装错误（如 command not found 或 TLS 失败）请参见安装排错。

除包装器与 IDE 错误（由启动程序而非 Claude Code 本身打印）外，这些错误和恢复命令适用于 CLI、Desktop 和 Claude Code on the web，因为三者包装的是同一个 Claude Code CLI。各界面特有的问题参见对应页面的排错章节。

Claude Code 调用 Claude API 获取模型响应，大多数运行时错误对应底层 API 错误码。原始 HTTP 状态码定义参见 Claude Platform 错误参考。

错误速查表¶

自动重试¶

Claude Code 在显示错误前自动重试瞬态故障，最多 10 次指数退避。 当响应已部分完成时并非总是重试。你看到本页错误时，Claude Code 已耗尽所有重试次数（除非该故障本身不重试）。

会重试的故障：

• 服务器错误、过载响应、请求超时
• 断连（连接在响应中途断开但 Claude 尚未完成任何可见内容前，重新发送请求继续该轮）
• 临时 429 限流（包括订阅用户登录时不带计划配额 header 的 429）

不重试的故障：

• TLS 证书验证失败（第一次尝试即报错，便于立即修复证书配置）。瞬态 TLS 条件如握手超时仍然重试。
• 响应已部分完成后的服务器错误/断连/流停滞：重发请求可能重复执行同一工具调用，因此保留已完成内容并附加响应可能不完整通知。
• Amazon Bedrock 流式响应 content-type 不匹配：网关会以同样方式改写重试。

重试期间你看到什么¶

重试时 spinner 显示 Retrying in Ns · attempt x/y 倒计时，前有错误标签。标签对可立即采取行动的故障（网络断开、TLS 握手失败、限流）从首次尝试就显示具体原因；其他错误先显示 API error，到第三次尝试后切换为具体原因。

重试期间常规 spinner 提示被抑制。当故障是 529 过载时，倒计时下方还会显示状态页地址（Anthropic API 为 status.claude.com，其他配置为对应提供商或网关主机）。

如果响应流 20 秒无数据到达，spinner 显示 Waiting for API response · will retry in ... · check your network。请求尚未失败：倒计时结束时 Claude Code 中断停滞连接，然后重试或以错误结束。如果每次尝试都出现此横幅，按网络错误处理。Claude 咨询 advisor 时阈值为 90 秒（因为 advisor 审查本身可能较久无数据）。

调整重试行为¶

服务器错误¶

本节大部分错误来自推理提供商。 Anthropic API 的来自 Anthropic 服务端；Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 或自定义网关的来自对应端点。Auto mode 无法判断动作安全性和 Agent terminated early 还涵盖你侧的原因（如 AWS 账户无法调用分类器模型、子代理达到使用限额）。

API Error: 500 Internal server error¶

API 内部意外故障，非你的 prompt、设置或账户导致。

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

消息尾部提示检查服务状态的地址因提供商而异（Bedrock/Vertex/Foundry 指向各自状态页，自定义 ANTHROPIC_BASE_URL 指向网关主机）。

处理：

• 检查 status.claude.com 或消息中的状态页
• 等一分钟重试；原始消息仍在对话中，可输入 try again
• 若持续无公告事件，运行 /feedback 报告

API Error: Repeated 529 Overloaded errors¶

API 全局满载，不是你的使用限制，不计入配额。 Claude Code 已重试多次后才显示此消息。

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

处理：

• 检查状态页查看容量通知
• 几分钟后重试
• 运行 /model 切换模型继续工作（容量按模型跟踪）。高负载时 Claude Code 会提示切换，例如 Opus is experiencing high load, please use /model to switch to Sonnet

Request timed out¶

API 在连接截止时间前未响应。 默认请求超时 10 分钟。高负载或生成超长响应时可能触发。

处理：

• 重试请求
• 长任务拆分为更小的 prompt
• 慢网络或代理导致时提高 API_TIMEOUT_MS（参见自动重试）
• 频繁超时且网络正常时参见网络错误

响应可能不完整¶

流式请求在 Claude 已开始产生响应后失败。 重发请求可能重复执行工具调用，因此 Claude Code 保留已完成输出并附加通知，而非丢弃该轮。具体变体指明原因：

API Error: Server error mid-response. The response above may be incomplete.
API Error: Connection closed mid-response. The response above may be incomplete.
API Error: Response stalled mid-stream. The response above may be incomplete.

• Server error mid-response：流中途收到过载或 5xx 错误
• Connection closed mid-response：连接断开
• Response stalled mid-stream：流停止发送数据

在 Claude 开始响应之前发生的故障不会显示此通知——要么重试，要么以其他错误结束。

处理：

• 交互会话中：阅读屏幕上保留的响应（最后未完成的块会被丢弃），回复 continue 让 Claude 从最后完成的块接续
• 非交互模式 (-p)：默认文本输出时打印最后完成的文本块加此消息；--output-format json 时在 result 字段报告；可恢复会话发送 continue 继续

Auto mode 无法判断动作安全性¶

Auto mode 的分类器未能产生决策。 读取、搜索和工作目录内的编辑跳过分类器，不受影响。

分类器失败可能呈现为多种消息：

分类器模型不可用时：

<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now.

可能是过载/限流（瞬态，重试可恢复），也可能是 AWS 账户未授权调用该模型（每次重试都失败直到授权）。

处理： 几秒后重试（Claude 通常自动重试）；在 Amazon Bedrock 上若每次都失败，检查 IAM 策略是否允许调用消息中指定的模型。

分类器返回不可解析响应时：

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

处理： 重试（通常下次成功）；用 claude --debug 查看调试日志中的分类器响应。

API 安全检查因对话内容阻止了分类器请求时：

Auto mode could not evaluate this action and is blocking it for safety — a safety check separate from auto mode blocked this request because of earlier conversation content

处理： 这与你的动作无关，是对话中的内容触发了过滤器。重试无效。切换权限模式手动审批，或开始不含触发内容的新对话。

对话超过分类器上下文窗口时：

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

交互会话中 auto mode 回退为正常权限提示让你手动审批。非交互模式中运行中止。

处理： 审批或拒绝出现的提示；运行 /compact 缩减对话大小。

Agent terminated early due to an API error¶

子代理的 API 请求终端失败（如达到使用限额或重试耗尽），子代理在完成任务前停止。

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

处理：

• 根据冒号后的错误详情在本页对应章节查找修复步骤
• 底层错误清除后，让 Claude 重试任务或恢复子代理

当限流/过载/服务器错误中断已产生文本输出的前台子代理时，Claude 收到标记为不完整的部分输出而非此错误。

使用限额¶

本节大部分错误表示账户或计划绑定的配额已用完。 两个例外：Server is temporarily limiting requests 是与计划配额无关的服务端限流；Usage credits required for 1M context 是权限检查而非配额耗尽。

You've hit your session limit¶

订阅计划的滚动使用额度已用完。

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

session 和 weekly 限额跨所有模型共享，切换模型不能恢复。Opus 限额仅针对 Opus 请求，切换到其他模型可继续工作。用量同时计入 session 和 weekly 额度，单次大量工作流可在 session 重置前耗尽 weekly 额度。

处理：

• 等待消息中的重置时间
• Opus 限额下运行 /model 切换其他模型
• 运行 /usage 查看计划限额和重置时间
• 运行 /usage-credits 购买额外用量（Pro/Max），或请管理员启用（Team/Enterprise）。参见付费计划额外用量
• 升级计划获取更高基础限额：claude.com/pricing

要在达到限额前监控剩余额度，可在自定义状态栏添加 rate_limits 字段，或在 Desktop 应用点击模型选择器旁的用量环。

Usage credits required for 1M context¶

选择的模型使用 1M 扩展上下文窗口，你的计划仅通过 usage credits 提供此功能。

API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

这是权限检查，不是配额耗尽。即使 session 和 weekly 额度仍有余量也会触发。参见扩展上下文了解哪些计划直接包含 1M 上下文、哪些需要 usage credits。

当此错误出现在对话中途（上下文超过 200K token 时），Claude Code 自动压缩对话并保持在标准上下文限制以下，无需操作。

处理：

• 运行 /model 选择无 [1m] 后缀的变体
• 运行 /usage-credits 开启按量计费
• 若 /model 后仍报错，可能其他位置设置了 1M 模型 ID，参见模型问题按优先级检查
• 从模型选择器完全移除 1M 变体：设置 CLAUDE_CODE_DISABLE_1M_CONTEXT=1

Server is temporarily limiting requests¶

API 施加了短暂限流，与你的计划配额无关。

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

Claude Code 通过请求中缺少统一配额 header 来区分此限流和计划限额。此错误在自动重试退避后才显示。

处理： 短暂等待重试；持续时检查 status.claude.com。

Request rejected (429)¶

你的 API key、Amazon Bedrock 项目或 Google Cloud 项目达到了配置的速率限制。

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

处理：

• 运行 /status 确认活动凭据是你预期的那个（误设的 ANTHROPIC_API_KEY 可能路由到低层级 key）
• 在提供商控制台检查当前限制并申请更高层级
• Anthropic API key 参见速率限制参考
• 降低并发：降低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY，减少并行子代理，或脚本化运行时切换小模型

Credit balance is too low¶

Console 组织的预付费额度已用完。

处理：

• 在 platform.claude.com/settings/billing 充值，并考虑启用自动充值
• 有 Pro/Max/Team/Enterprise 计划时用 /login 切换为订阅认证
• 在 Console 设置工作区花费上限防止单项目耗尽组织余额。参见有效管理成本

Could not update your spend limit¶

服务器拒绝了你在达到花费限额时的提示中所做的限额变更。

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

当服务器给出拒绝原因时，以该原因结尾，重试同一值仍会失败。无服务器原因（如连接断开）时显示 Could not update your spend limit. Press Enter to retry.，重试可能成功。

处理：

• 若消息包含原因，选择满足条件的限额值
• 若仅显示通用形式，重试（可能是瞬态故障）
• 持续失败时在浏览器的 claude.ai 账单设置中操作

认证错误¶

这些错误意味着 Claude Code 无法向 API 证明你的身份。 随时运行 /status 查看当前活动凭据。

Not logged in¶

无可用凭据。

Not logged in · Please run /login

处理：

• 运行 /login 认证
• 若期望环境变量认证，确认 ANTHROPIC_API_KEY 在启动 claude 的 shell 中已设置并 export
• CI 或自动化中无法交互登录时，配置 apiKeyHelper 脚本在启动时获取密钥
• 参见认证优先级了解多凭据并存时哪个生效
• 反复提示登录时参见登录排错检查系统时钟和 macOS Keychain

Could not resolve authentication method¶

会话到达 API 客户端时无任何凭据。 出现在后台会话、云会话和 Agent SDK 上下文中。

Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set.

处理：

• 升级到 v2.1.174+（修复了后台/云会话中的竞态问题）
• 确认 ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN 或云提供商凭据设置在启动 worker 的环境中
• Agent SDK 参见快速开始认证设置
• 在相同环境的交互会话中运行 /status 确认凭据来源

Invalid API key¶

ANTHROPIC_API_KEY 或 apiKeyHelper 返回的密钥被 API 拒绝。

Invalid API key · Fix external API key

处理：

• 检查拼写并确认密钥未在 Console 中被撤销
• 运行 env | grep ANTHROPIC 检查（direnv、dotenv 插件、IDE 终端可能从 .env 加载了过期 key）
• 取消设置 ANTHROPIC_API_KEY 后运行 /login 使用订阅认证
• 若密钥来自 apiKeyHelper 脚本，直接运行该脚本确认它在 stdout 输出有效密钥
• 运行 /status 确认 Claude Code 实际使用的凭据来源

Your apiKeyHelper script is failing¶

apiKeyHelper 配置的命令退出错误、超时或无 stdout 输出。 无密钥时请求带占位凭据到达 API 被拒绝为 401。Claude Code 重试脚本最多两次后才显示此消息。

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

运行 /login 在此无效：helper 输出优先于保存的登录。

处理：

• 在 shell 中直接运行 apiKeyHelper 配置的命令重现失败
• 若命令报告会话过期，重新认证你的凭据提供者（如 SSO/secrets vault）
• 修复命令使其向 stdout 输出密钥并以代码 0 退出。参见使用 apiKeyHelper 轮转凭据
• 运行 /status 确认 apiKeyHelper 是活动凭据来源

This organization has been disabled¶

过期 ANTHROPIC_API_KEY（来自已禁用的 Console 组织）覆盖了你的订阅登录。

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials

环境变量优先于 /login，即使你有可用的 Pro/Max 订阅。

处理：

• 在当前 shell 取消设置 ANTHROPIC_API_KEY 并从 shell profile 移除，重启 claude
• 运行 /status 确认活动凭据是你的订阅
• 若未设环境变量仍报错，则禁用组织绑定在你的 /login。联系支持或用其他账户登录

Your organization has disabled API key authentication¶

Console 组织管理员关闭了 API key 认证。 消息尾部的恢复提示因密钥来源而异。

环境变量和 apiKeyHelper 优先于 /login，所以仅运行 /login 不够（密钥仍在提供中）。

处理：

• 若消息指名 ANTHROPIC_API_KEY，取消设置并从 profile/.env 移除，重启 claude
• 若消息指名 apiKeyHelper，从 settings.json 移除该设置
• 运行 /login 用 claude.ai 账户登录
• 运行 /status 确认活动凭据是订阅而非 API key
• 自动化需要 API key 时请组织管理员在 Console 重新启用

Your organization has disabled Claude subscription access¶

你的 Claude 组织不允许用订阅登录访问 Claude Code。

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

这是服务端组织设置，无法通过本地设置、环境变量或 CLI flag 覆盖。

处理：

• 请管理员启用组织的 Claude Code 访问
• 改用 Console API key 认证。参见 Claude Console 认证
• 若你是管理员且未看到启用选项，联系 Anthropic 支持

Routines are disabled by your organization's policy¶

Team/Enterprise 组织的 Owner 关闭了 routines 功能。 尝试创建或运行 routine（包括 /schedule 和 Routines UI）时出现。

Routines are disabled by your organization's policy.

处理：

• 请 Owner 在 claude.ai/admin-settings/claude-code 启用 Routines 开关
• 不需要组织级 routines 的一次性定时工作可参见定时任务

Remote Control requires the Anthropic API¶

会话未直接连接 Anthropic API，无法配对 Remote Control。

Remote Control is only available when using Claude via api.anthropic.com.

出现在 Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundry 上，以及 ANTHROPIC_BASE_URL 指向非 api.anthropic.com 的主机时。

处理：

• 取消设置 ANTHROPIC_BASE_URL 并重启会话，或从直连 Anthropic API 的会话启动 Remote Control
• 更多 Remote Control 启动消息参见排错

OAuth token revoked or expired¶

保存的登录不再有效。 revoked 表示你在所有地方退出或管理员移除了访问；expired 表示自动刷新在会话中失败。

OAuth token revoked · Please run /login
OAuth token has expired · Please run /login

处理：

• 运行 /login 重新登录
• 若重新认证后同一会话内再次出错，先运行 /logout 完全清除令牌再 /login
• 反复提示登录参见排错中的系统时钟和 macOS Keychain 检查

API Error: 401 Invalid authentication credentials¶

API 识别了凭据格式但拒绝了其背后的账户或组织。 可能是凭据被撤销、组织被禁用/移除了你的访问、或账户被停用。不同于 token 过期。

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

处理：

• 若 /status 显示 API key 行，已批准的 ANTHROPIC_API_KEY 优先于登录。在 Console 轮转密钥，或 unset ANTHROPIC_API_KEY
• 若 /status 仅显示登录，运行 /login
• 若同一账户反复出现，账户或组织已不活跃，联系管理员恢复访问
• 若 ANTHROPIC_BASE_URL 指向 LLM 网关，401 后的文本是网关消息，修复网关凭据

Login expired¶

Claude Code 尝试续期 OAuth 登录被拒绝，已清除保存的凭据。 每个后续请求在本地停止（不发往 API），因为只有 /login 能创建新凭据。

Login expired · Please run /login

非交互模式 (-p) 和 Agent SDK 中消息为：

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

与 OAuth token revoked or expired 不同：后者报告 API 返回的 401，而此消息是 Claude Code 自身在刷新失败后生成的。

可通过 /status 检查此状态：显示 Login 行读作 Expired — log in again，以及保存的组织和邮箱。

处理：

• 运行 /login 重新登录。不登录直接重试会每个请求都显示相同消息
• 非交互模式中先在同环境运行 claude 完成 /login 再重跑命令；无法交互登录的自动化用 ANTHROPIC_API_KEY 或 claude setup-token
• 登录持续失败参见登录排错

OAuth scope requirement¶

存储的 token 早于某个新功能所需的权限范围。 常见于 /usage 和状态栏用量指示器。

OAuth token does not meet scope requirement: user:profile

处理： 运行 /login 获取包含当前 scope 的新 token。无需先退出。

AWS credentials expired or invalid¶

AWS 会话令牌过期或被拒绝，Claude Code 已运行的自动刷新未能产生 API 接受的凭据。 需 v2.1.198+ 且设置了 awsAuthRefresh。

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

未配置 awsAuthRefresh 时，同样的 401 显示通用 Please run /login 消息。

处理：

• 在另一终端运行消息中指定的 awsAuthRefresh 命令（如 aws sso login）并完成浏览器登录，然后重试
• 交互会话中运行 /login，选择 3rd-party platform > Claude Platform on AWS · refresh credentials
• 刷新成功后仍报错时用 aws sts get-caller-identity 在同 shell 和 profile 中验证身份

AWS authentication failed¶

AWS 提供商返回 403，或 Amazon Bedrock 返回 401。 需 v2.1.198+ 且设置了 awsAuthRefresh。

Claude Code 无法区分原因：Bedrock 用 403 报告过期令牌，但 403 也可能是 IAM 权限缺失或模型未启用。

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

处理：

• 运行 awsAuthRefresh 命令或 aws sso login（以防是过期凭据）
• 凭据当前有效时确认 IAM 配置中的权限已附加到你的身份且模型已在账户/区域启用
• 运行 aws sts get-caller-identity 确认请求使用的身份

AWS default-chain credential resolve timed out¶

AWS 默认凭据提供链 60 秒内未产生凭据。 失败是本地凭据解析——请求从未到达 Bedrock/Claude Platform on AWS/Mantle 端点。

API Error: AWS default-chain credential resolve timed out

常见原因：AWS profile 中的 credential_process 等待无法接收的输入；容器/VM 的实例元数据服务 (IMDS) 未响应。

处理：

• 在同一 shell 同一 AWS_PROFILE 运行 aws sts get-caller-identity。若也挂起则修复 profile
• 在启动 Claude Code 前完成登录步骤（如 aws sso login），使链从本地 SSO 缓存解析
• 交互登录确实需要超过 60 秒时，用 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 提高超时

网络错误¶

这些错误意味着 Claude Code 的网络请求未能到达目的地，或中间设备篡改了返回的响应。 通常源于本地网络、代理、防火墙或云环境的网络策略。

Unable to connect to API¶

到 API 的 TCP 连接失败或未完成。

Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API (ECONNRESET)
Unable to connect to API (ETIMEDOUT)
fetch failed
Request timed out. Check your internet connection and proxy settings

常见原因：无网络、VPN 阻止 api.anthropic.com、需要企业代理但未配置。

处理：

• 在同一 shell 运行 curl -I https://api.anthropic.com 确认连通（Windows PowerShell 用 curl.exe）
• 企业代理环境设置 HTTPS_PROXY，参见网络配置
• 通过 LLM 网关/中继时设置 ANTHROPIC_BASE_URL，参见连接 LLM 网关
• 确保防火墙允许网络访问要求中的域名
• 间歇性故障会自动重试；持续失败指向本地网络问题

若 curl 成功但 Claude Code 仍失败，原因通常在运行时和网络之间：

• Linux/WSL：检查 /etc/resolv.conf 是否有不可达的 nameserver
• macOS：断开的 VPN 可能遗留隧道接口或路由规则，检查 ifconfig 中的 utun 接口
• Docker Desktop 等容器运行时可拦截出站流量，退出后重试排除

Socket is closed¶

连接在流式响应仍在到达时被关闭。 最常见原因是 Windows 上的企业代理中途断开已建立的隧道。

当中断响应中尚无完成内容时，Claude Code 视为断连并自动重试。Claude 已完成文本/工具调用后，保留输出并附加响应可能不完整通知。

处理：

• 更新到 v2.1.214+（该版本开始重试此故障），然后重新发送消息
• 更新后仍反复失败时按网络配置检查代理设置

Bedrock streaming response has an unexpected content-type¶

Claude Code 与 Amazon Bedrock 之间的网关/代理篡改了流式响应体或其 Content-Type header。 Bedrock 以 application/vnd.amazon.eventstream 流式返回，Claude Code 拒绝报告不同 content-type 的成功响应。不重试。

Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body...

处理：

• 配置网关透传 InvokeModelWithResponseStream 响应体及其 Content-Type header
• 若网关仅改写 header 但二进制 body 完好，设置 CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 跳过检查。参见网关后流式错误

SSL 证书错误¶

代理或安全设备用自己的证书拦截 TLS 流量，Claude Code 不信任它。

Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates
Unable to connect to API: Self-signed certificate detected

证书验证失败不重试，首次尝试即报错。/login 和启动连通性检查中以 OpenSSL 代码和修复建议报告同一故障。

处理：

• 导出组织 CA 包并设置 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem
• 参见网络配置获取完整设置说明
• 不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0（完全禁用证书验证）

Host not allowed in a cloud session¶

云会话或 routine 的出站 HTTP 请求被环境网络策略阻止。

HTTP 403
x-deny-reason: host_not_allowed

也可能看到与目的地真实证书不匹配的 TLS 证书——云会话通过代理路由出站流量，证书不匹配意味着代理终止了连接。

云会话和 routines 在沙盒 VM 中运行，出站流量被过滤到云环境允许列表。GitHub 操作和 MCP connector 流量用单独通道（因此其他域被阻止时它们仍可工作）。Default 环境使用 Trusted 访问，允许包管理器、云提供商 API、容器注册表等默认允许列表并阻止其他域。

处理：

• 打开 routine 编辑或云会话，选择云图标打开选择器，悬停环境并点击设置图标
• 在 Update cloud environment 对话框中将 Network access 从 Trusted 改为 Custom，添加被阻止的域（每行一个）。勾选 Also include default list 保留默认允许列表。选择 Full 获取无限制访问
• 点击 Save changes，下次运行使用更新的允许列表

本地 CLI 会话不受此策略影响。

Couldn't reconnect to your Remote Control session¶

恢复会话时重连 Remote Control 会话失败。 可能是网络中断或服务器错误等暂时原因。本地会话保持运行但无 Remote Control。

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

处理：

• 运行 /remote-control 重试连接
• 不带 --resume 启动 Claude Code 创建新 Remote Control 会话
• 更多 Remote Control 启动消息参见排错

请求错误¶

这些错误与请求内容相关。 多数来自 API 拒绝请求后的返回；少数由 Claude Code 在发送请求前本地产生。

Prompt is too long¶

对话加附件超出模型上下文窗口。

Prompt is too long

处理：

• 运行 /compact 摘要早期轮次释放空间，或 /clear 开始新对话
• 运行 /context 查看窗口占用分布（系统 prompt、工具、memory 文件、消息）
• 用 /mcp disable <name> 禁用不用的 MCP 服务器移除其工具定义
• 精简大型 CLAUDE.md 文件，或将指令移入路径范围规则按需加载
• 子代理继承父会话所有 MCP 工具定义，可能在首轮前就填满上下文窗口
• auto-compact 默认开启可防止此错误。若设置了 DISABLE_AUTO_COMPACT，重新启用或手动 /compact

参见探索上下文窗口获取交互式视图。

Context exceeds the token limit¶

/context 在输出顶部显示此警告，表示对话超过模型上下文窗口。 请求将以 Prompt is too long 失败直到释放空间。

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

当超过的是小于模型上下文窗口的压缩窗口时：

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

处理： 运行 /compact 或 /clear；更多方法参见 Prompt is too long。

Error during compaction: Conversation too long¶

/compact 本身失败，因为没有足够空闲上下文容纳其产生的摘要。

Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

处理：

• 按 Esc 两次打开消息列表，回退几轮（丢弃最近消息释放空间），再运行 /compact
• 若仍不够空间，运行 /clear 开始新会话（之前对话保留，可用 /resume 重新打开）

Request too large¶

原始请求体超过 API 的 32MB 限制（通常因大文件粘贴或附件）。

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

这是 HTTP 请求大小限制，独立于上下文窗口限制。Claude Code 直连 Claude API 时通过丢弃最旧的图片/附件保持在此限制以下。

处理：

• 运行 /compact 摘要对话（丢弃累积的图片/附件）
• 按 Esc 两次回退到添加超大内容的轮次之前
• 用路径引用大文件而非粘贴内容

Image was too large¶

粘贴或附加的图片超过 API 的大小或尺寸限制。

Image was too large. Double press esc to go back and try again with a smaller image.

Claude Code 用文本占位符替换不可处理的图片并重试，后续消息可成功。

处理：

• 粘贴前调整图片大小（API 单张最大 8000 像素长边；多张在上下文中时 2000 像素）
• 截取相关区域而非全屏

Unable to resize image¶

Claude Code 无法在发送前缩小附加的图片。 正常情况下自动缩放，这些错误表示原生图片处理器加载/运行失败。

处理：

• 若消息要求转换格式，转为 PNG/JPEG/GIF/WebP 后重新附加
• 若消息报告尺寸/大小限制，手动缩放或重新压缩到限制以下

PDF errors¶

附加的 PDF 无法处理。

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

处理：

• 过大 PDF：让 Claude 用 Read 工具读取页范围，或用 pdftotext 提取文本后引用文件路径
• 受保护/无效 PDF：移除密码或从源应用重新导出

Extra inputs are not permitted¶

Claude Code 与 API 之间的代理或 LLM 网关剥离了 anthropic-beta 请求 header，导致 API 拒绝依赖它的字段。

API Error: 400 ... Extra inputs are not permitted ... context_management
API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples

Claude Code 发送 beta 字段（如 context_management、effort、工具 input_examples）时附带 anthropic-beta header 启用它们。网关转发 body 但丢弃 header 时 API 不识别这些字段。

处理：

• 配置网关转发 anthropic-beta header。参见功能透传
• 备选方案：设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 禁用需要 beta header 的功能

There's an issue with the selected model¶

配置的模型名未识别或账户无权访问。

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

处理：

• 交互 CLI：运行 /model 从可用模型中选择
• 非交互模式 (-p)：传 --model 加有效别名或 ID，或设置 ANTHROPIC_MODEL
• Agent SDK：在 TypeScript 设置 model on Options，Python 设置 ClaudeAgentOptions(model=...)
• 使用 sonnet 或 opus 等别名（不过期），而非完整版本 ID
• 错误模型持续出现时按优先级顺序检查：--model flag > ANTHROPIC_MODEL 环境变量 > .claude/settings.local.json > 项目 .claude/settings.json > ~/.claude/settings.json，移除过期值
• 新模型可能在 Anthropic API 上可用但 Bedrock/Vertex/Foundry 尚未提供

Model is not a recognized model id¶

模型字符串不是别名、已知 ID，也不以 claude- 开头。 通常是拼写错误、用了显示名（如 Sonnet 5）而非 ID、或别名只有更新版本支持。

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

处理：

• 运行 /model 无参数打开选择器
• 若用了新版本才支持的别名，运行 claude update
• 此检查仅在 Anthropic API 上运行。Bedrock/Vertex/Foundry/LLM 网关上 Claude Code 接受任何字符串并透传

Claude Opus is not available with the Claude Pro plan¶

当前订阅计划不包含所选模型。

Claude Opus is not available with the Claude Pro plan · Select a different model in /model

处理：

• 运行 /model 选择计划包含的模型
• 近期升级计划后仍报错时运行 /logout 再 /login（存储的 token 反映签入时的计划）
• 参见 claude.com/pricing 查看各计划包含的模型

Model is restricted by your organization's settings¶

组织管理员在 claude.ai 管理后台禁用了此模型，或 availableModels 允许列表排除了它。 当受限模型通过 --model/ANTHROPIC_MODEL/model 设置指定时，Claude Code 替换为允许的模型并继续。

Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

处理：

• 运行 /model 从组织允许的模型中选择（受限模型从选择器隐藏）
• 移除或更新 --model/ANTHROPIC_MODEL/settings 中的受限值以避免每次启动出现通知
• 需要访问受限模型时请管理员启用。参见组织模型限制

thinking.type.enabled is not supported for this model¶

Claude Code 版本低于所选模型所需的最低版本。

API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

处理：

• 运行 claude update 并重启。版本要求：Opus 4.7 需 v2.1.111+；Opus 4.8 需 v2.1.154+；Sonnet 5 需 v2.1.197+；Opus 5 需 v2.1.219+
• 无法升级时运行 /model 选择 Opus 4.6 或 Sonnet 4.6
• Agent SDK 中升级 SDK 包：Opus 4.8 需 TS SDK v0.3.154+/Python SDK v0.2.88+；Sonnet 5 需 TS SDK v0.3.197+；Opus 5 需 TS SDK v0.3.219+

Thinking budget exceeds output limit¶

配置的扩展思考预算超过最大响应长度，实际回答无剩余空间。

API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

Claude Code 在 Anthropic API 上自动调整这些值。此错误通常在 Bedrock/Vertex 上出现（MAX_THINKING_TOKENS 设高于提供商输出限制，或 plan mode 提升了思考预算）。

处理：

• 降低 MAX_THINKING_TOKENS，或将 CLAUDE_CODE_MAX_OUTPUT_TOKENS 提高到思考预算以上
• 参见扩展思考了解预算与输出长度的交互

Tool use or thinking block mismatch¶

对话历史以不一致状态到达 API，通常在工具调用被中断或轮次被中途编辑后。

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks
API Error: 400 ... thinking blocks ... cannot be modified

三种变体含义相同：历史中的 tool_use、tool_result 和 thinking 块序列不再匹配 API 预期。

处理：

• 使用 Opus 4.7/4.8 时先运行 claude update（v2.1.156 前正常工具使用可触发此错误）
• 运行 /rewind 或按 Esc 两次回退到损坏轮次前的检查点。参见检查点

Usage Policy refusal¶

API 因对话内容触发使用政策检查而拒绝响应。 消息包含 Request ID 可引用于支持。

API Error: Opus 4.6 can't help with this. Start a new session to continue.
Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup

检查评估整个对话（不仅是最新 prompt），同一会话中发新消息通常重新触发拒绝。退出后用 --continue/--resume 重开也同样（磁盘上的记录仍含触发内容）。

处理：

• 按 Esc 两次或运行 /rewind 回退到触发拒绝的轮次之前，重新措辞或换一种方式。参见检查点
• 无法确定哪轮导致时运行 /clear 开始新对话（之前对话保留在 /resume 中）
• 非交互模式 (-p) 中用新会话重试（不带 --continue），换模型 --model 也可能解决

Safety measures flagged a cybersecurity topic¶

模型的安全措施将对话内容标记为网络安全话题。

API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program...

消息链接到 Cyber Verification Program，为合法网络安全工作授予访问。

不同提供商和模式下的表现：
- Bedrock/Vertex/Foundry 上显示 Usage Policy refusal 消息
- 非交互模式中最后一句读作 Learn more: 后接链接

处理：

• 工作需要此内容时通过 Cyber Verification Program 申请访问
• 请求非网络安全话题时运行 /feedback 报告误报
• 继续同一会话工作：按 Esc 两次或 /rewind 回退并换方式

安装错误¶

这些错误出现在安装或更新 Claude Code 时。 command not found、PATH、权限和 TLS 问题参见安装排错。

Installation was killed before it could finish¶

安装脚本报告 claude install 步骤被信号终止。 Linux 上退出码 137 意味着内核 OOM killer 终止了进程。

Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

其他致命信号和 macOS 上的 137 打印不同措辞且省略 OOM 解释。消息来自 macOS/Linux 安装脚本（含 WSL）；Windows 原生安装脚本不打印此消息。

处理：

• 停止其他进程释放内存后重试
• 添加 swap 空间或使用更大实例。参见低内存 Linux 服务器安装

The connection dropped while downloading the update¶

下载 Claude Code 二进制时连接断开，重试未恢复。 Claude Code 在连接断开、传输停滞或校验失败时最多重试 3 次。

The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

10 分钟内未完成的下载以 Download timed out: exceeded the total deadline 失败（不重试，因为太慢的连接重试也完成不了）。

常见原因是代理/网关在长传输完成前关闭连接。Claude Code 二进制较大，正常 API 流量不受影响的代理连接限制可能中断它。

处理：

• 再次运行 claude update（健康网络上通常下次成功）
• 超时消息则从更快/无限流的网络运行
• 需要代理时设置 HTTPS_PROXY，参见检查网络连通性
• 企业代理持续断开时请网络团队允许 downloads.claude.ai 完整下载，参见网络访问要求
• 运行 claude doctor 获取安装诊断

命令行错误¶

这些错误来自 claude 命令行、子命令以及 /security-review 等在运行 prompt 前收集上下文的命令。

Conflict between --bg and --print¶

--bg 与 -p/--print 组合冲突。 --bg 启动可通过 claude agents 附加的后台会话，--print 非交互运行永不启动交互会话。

--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable.

处理：

• 去掉 -p/--print。--bg 将 prompt 作为位置参数：claude --bg "<task>"。参见从 shell 分发代理
• 若需非交互运行并打印结果（而非后台会话），去掉 --bg：claude -p "<task>"

The --json-schema value is not a valid JSON Schema¶

--json-schema 传入的 schema 编译失败，claude 以代码 1 退出。

Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

第二个冒号后是验证器诊断，指明失败的关键字或位置。使用 format 关键字（如 "format": "email"）的 schema 是有效的（Claude Code 接受 format 为注解）。

处理：

• 修复诊断指名的 schema 部分后重跑
• 诊断为 schema too large 时减少 schema 嵌套和 $ref 复用
• 参见获取结构化输出

Settings file exceeds the 2MiB limit¶

--settings 传入的文件大于 2 MiB。 设置文件是小 JSON 文档，这么大通常意味着路径指向了错误文件。

Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

非常规文件（设备、FIFO、socket）报告 Not a regular file；目录报告 EISDIR。

处理： 将 --settings 指向 2 MiB 以下的常规 JSON 设置文件。参见 Settings。

Workspace not trusted when starting Remote Control¶

在未信任的目录中启动 Remote Control 服务器模式时报错退出。

Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

在 home 目录中消息不同（home 目录的信任对话框不保存信任）：

Error: Workspace not trusted. /Users/you is your home directory... Run `claude rc` from a project directory instead.

处理：

• 在该目录运行 claude 接受工作区信任对话框，然后重新运行 claude remote-control
• home 目录中切换到项目目录启动 Remote Control

Could not import a server from Claude Desktop¶

claude mcp add-from-claude-desktop 无法添加你选择的某个服务器。 命令仍导入其他选中的服务器，并为每个失败的打印一行。

Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

最常见原因是名称检查：Claude Desktop 允许空格和句号，claude mcp 仅允许字母、数字、连字符和下划线。

处理：

• 在 claude_desktop_config.json 中重命名服务器为有效名称后重试
• 用 claude mcp add 或 claude mcp add-json 在有效名称下直接添加。参见从 Claude Desktop 导入 MCP 服务器

MCP permission prompt tool not found¶

--permission-prompt-tool 传入的工具在需要权限决策时不在已连接的 MCP 工具中。 运行在首个需要审批的工具调用时以此错误和代码 1 退出。

Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

处理：

• 检查服务器启动并保持连接：claude mcp list 确认服务器列为已连接
• 确认工具名匹配 mcp__<server>__<tool> 格式
• 服务器启动需超过 30 秒时提高 MCP_TIMEOUT

/security-review fails without origin/HEAD¶

/security-review 通过 diff 你的分支与 origin/HEAD 构建审查上下文。当该 ref 不存在时 git 命令失败。

Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]
fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree.

git 仅在远程默认分支被远程通告且被 fetch refspec 覆盖时才创建此 ref。完整 git clone 满足条件；单分支和 CI checkout 可能不满足。

处理：

• 指定远程默认分支创建 ref：git remote set-head origin <default-branch>
• 若不想指定分支：git fetch origin && git remote set-head origin --auto
• 仓库无 remote 时先 git remote add origin <url> 并 fetch

Input must be provided when using --print¶

裸 claude 需要 stdout 为终端才能启动交互 UI。 stdout 被重定向或控制台非真实终端（如 PowerShell ISE）时进入非交互模式，需要 prompt 输入。

Error: Input must be provided either through stdin or as a prompt argument when using --print

处理：

• 交互使用：在真实终端中运行 claude（Windows Terminal/PowerShell 控制台，IDE 的集成终端而非输出面板）
• 一次性使用：传 prompt claude -p "your question"，或管道 echo "your question" | claude -p

Diff is too large for ultrareview¶

分支与 base branch 的 diff 超过 ultrareview 大小限制，审查在云会话启动前被拒绝。 被拒审查不使用免费运行也不计费。

Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines)...

处理：

• 传更近的 base branch：/code-review ultra develop
• 将变更拆分为更小分支分别审查（消息指名贡献最多变更行的文件，从它们开始拆分）

Failed to resume the conversation¶

Claude Code 无法读取或处理 claude --resume 选择器中选择的会话的保存记录。

Failed to resume the conversation.
Run claude --resume <session-id> to retry, or claude to start a new session.

Claude Code 以代码 1 退出。运行中会话内的 /resume 选择器在对话中报告 Failed to resume conversation 并保持当前会话继续运行。

处理：

• 用消息中的 session ID 运行 claude --resume <session-id> 重试
• 若重试仍失败，运行 claude 开始新会话

插件错误¶

这些错误来自插件和市场配置。 不产生本页消息的插件问题（如市场 URL 无法加载、插件安装后不出现）参见插件排错。

Marketplace is registered from an untrusted source¶

市场注册名是官方 Anthropic 市场保留名，但注册来源不是 anthropics GitHub 仓库。 市场及其安装的插件停止加载。

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces.

处理：

• 运行 claude plugin marketplace remove <name>，然后从官方 github.com/anthropics 仓库重新添加
• 第三方市场若曾用此名，重命名后请用户从你的来源重新添加
• 保留名列表参见市场 Schema

Plugin command references user_config¶

插件 hook、monitor 或 MCP headersHelper 命令引用了 ${user_config.KEY}，替换后的字符串将传递给 shell。 配置值中含 $(...)、反引号或 ; 会作为代码执行，因此 Claude Code 拒绝启动该组件。

不同表面的措辞不同：

• Shell 形式 hook：Hook from plugin ... references ${user_config.*} in a shell-form command...
• Monitor：Monitor "..." from plugin ... references ${user_config.*} in its command...
• MCP headersHelper：headersHelper for MCP server '...' references ${user_config.*}...

处理：

• Hook：添加 args 数组使用 exec 形式（每个 ${user_config.KEY} 成为一个参数无 shell 介入），或去掉引用改读 $CLAUDE_PLUGIN_OPTION_<KEY> 环境变量
• Monitor：去掉引用，让 monitor 脚本从配置文件读取值
• headersHelper：将 ${user_config.KEY} 移到服务器 headers 字段（不经 shell 解析），或在 helper 脚本内读取值

工具错误¶

这些错误来自 Claude 的内置工具。 Claude 通常自行纠正大多数工具错误；前两个需要你修改，因为来自你控制的子代理定义或权限规则。

Agent would be spawned with zero tools¶

子代理 tools 列表中的所有条目都未匹配到可用工具，Claude Code 拒绝启动。 消息按失败原因分组：

• Unrecognized：不匹配任何工具名（通常拼写错误）
• Not available to subagents：工具存在但子代理不可用
• Matched no tools in this session：条目有效但当前会话无匹配工具（如 mcp__github__* 但无 GitHub MCP 服务器连接）

省略 tools 字段不会触发此拒绝。

Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe].

处理：

• 根据子代理可用工具修正每个错误条目
• 移除当前会话无对应工具的条目
• 后台子代理不支持的工具（如 LSP、TaskCreate）移除或让 Claude 在前台运行子代理
• 删除 tools 字段（给子代理所有可用工具）
• 仅含 Agent 的列表在深度限制时解析为零工具——提高限制或添加其他工具

File is covered by a Read deny rule¶

Edit 工具被调用的路径匹配了 Read deny 规则（含在该路径创建新文件）。 编辑需要能回读内容，因此在任何文件访问前被拒绝。该规则仅阻止 Edit 工具；Write 和 NotebookEdit 不受 Read deny 规则影响。

File is covered by a Read deny rule in your permission settings and cannot be edited.

处理：

• 若 Claude 应能编辑该文件，在 /permissions 或设置中移除/收窄 Read deny 规则
• 若文件必须保持不变，保留规则并为同一路径添加 Edit deny 规则以阻止 Write/NotebookEdit

Memory index is over its read limit¶

Claude 写入自动记忆索引 MEMORY.md 后使其超过读取限制之一：200 行或 25KB。 写入成功，但每次加载时超限部分被丢弃。

Error: this write left the memory index at MEMORY.md at 214 lines, over its 200-line read limit...

YAML frontmatter 和块级 HTML 注释加载前被剥离，不计入测量。Claude Code 将此错误交付给 Claude（非终端横幅），你可能只在记录中注意到。

处理：

• 让 Claude 重写 MEMORY.md：每条目一行、将详情移入主题文件、合并/删除过时条目
• 手动精简参见审计和编辑你的记忆

pkill pattern matches the Claude Code process¶

Bash 工具中的 pkill 命令的模式（通常带 -f）匹配了 Claude Code 进程本身。 Claude Code 先用 pgrep 测试模式，发现自身 PID 在结果中则拒绝。仅 Linux 生效；macOS 上 pkill 不修改运行。

pkill: refusing to run — this pattern matches the Claude CLI process (PID 12345). Narrow the pattern, or target your own children with `pkill -P $$ ...`.

处理：

• 收窄模式使其仅匹配目标进程（如使用目标二进制全路径）
• 停止当前 shell 启动的进程用 pkill -P $$

后台会话错误¶

后台会话无自己的交互终端，需要终端的命令行为不同。

Commands refused in a background session¶

打开交互对话框的命令在无终端附加到后台会话时无法执行。 /install-github-app、/mcp 设置列表和 MCP 服务器菜单中的认证操作会响应消息，会话出现在 agent view 的 Needs input 下。终端附加后这些命令正常工作。

Can't open MCP settings while no terminal is attached to this background session. This session now shows "needs input" in agent view...

处理：

• 从 agent view 附加到会话（在 Needs input 下列出），重新运行命令
• 或使用消息指名的形式（如 /mcp reconnect <server>、/mcp enable、/mcp disable），无需附加

This session has no saved transcript¶

附加到的已停止后台会话在首次响应完成前就被停止了。 对话仍只存在于它被后台化的会话中。

This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

处理：

• 你后台化的原始对话完好——用 claude --resume 恢复或继续在其中工作
• 仍要启动该停止会话时运行 claude respawn <id>，或在 agent view 中对该行按两次 Enter

Session agent no longer available¶

恢复的会话曾运行自定义代理（通过 --agent 或 agent 设置启动），但 Claude Code 未找到同名代理。 会话仍恢复，但使用默认工具和系统 prompt（代理的工具限制不再适用）。

This session was running agent 'code-reviewer', which is no longer available (no agent by that name in /home/you/project). Continuing with the default tools and system prompt...

处理：

• 在会话项目的 .claude/agents/<name>.md 或 ~/.claude/agents/<name>.md 重新创建代理文件后再次恢复
• 或用 --agent <name> 指定存在的代理恢复
• 项目范围代理且未信任原始目录时，先在那里运行 Claude Code 接受信任对话框

CLAUDE_CODE_PROCESS_WRAPPER launcher errors¶

CLAUDE_CODE_PROCESS_WRAPPER 已设置但其值不可用，Claude Code 拒绝启动受影响的进程。

CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file

启动但未 exec 替换自身的 launcher 使其启动的会话失败并报告 must exec, not daemonize。

处理：

• 将变量设为以 exec "$@" 结尾的可执行文件的绝对路径。参见launcher 契约
• 检查 /status（显示 Self-exec 条目中的解析启动命令），或运行 claude daemon status
• 修复 settings env 块中的值后用 claude daemon stop --any 重启后台服务

EUNKNOWN when starting a background session¶

Windows 以无标准名称的错误码拒绝启动程序。 通常是软件限制策略（Group Policy/AppLocker）阻止了程序。

Couldn't reach the background service (spawn background service: EUNKNOWN: unknown error, uv_spawn) — run 'claude daemon status'

Claude Code 通过 PowerShell 启动后台服务使其在关闭终端后存活（优先用 PowerShell 7，否则 Windows PowerShell 5.1）。两者都无法运行时直接启动服务。若仍报错则策略阻止的是 Claude Code 可执行文件本身。

处理：

• 消息为 Couldn't start the session 时升级到 v2.1.212+；旧版本可在另一终端先运行 claude daemon run（服务仅在该终端存活时运行）
• v2.1.212+ 仍报错时请 Windows 管理员在限制策略中允许 Claude Code 可执行文件
• 后台服务随终端关闭而停止时说明 Claude Code 未通过 PowerShell 启动——安装 PowerShell 7 或请管理员解除 PowerShell 阻止

包装器与 IDE 错误¶

这些错误来自启动 Claude Code 的程序（IDE 扩展或 Agent SDK 应用），而非 Claude Code 本身。

Claude Code process exited with code N¶

底层 claude 进程以非零代码退出。 退出码本身不说明失败原因——真正的错误在进程自身输出中。

Error: Claude Code process exited with code 1

处理：

• VS Code 中跟随 View output logs 链接查看底层失败
• 在同一项目的终端中运行 claude（通常在那里重现并显示真正错误消息，可在本页查找）
• 运行 claude doctor 检查安装和配置

回退警告¶

此警告来自 /rewind 代码恢复，报告恢复拒绝处理的路径。 其他所有跟踪文件的恢复已完成。

Restored the code, but skipped files¶

/rewind 代码恢复跳过了一个或多个跟踪路径而非写入/删除。 跳过原因：

• 路径是或已变为符号链接、硬链接或其他非常规文件
• 其目录自检查点以来已更改
• 其备份无法安全读取

跳过的路径保持当前内容。

Restored the code, but skipped 2 files: the tracked path is (or became) a link or other non-regular file...

处理：

• 识别跳过的文件：find . -type l（符号链接）和 find . -type f -links +1（硬链接文件）。开启调试日志（/debug）后日志中会列出每个跳过的路径
• 有意创建的链接（如 dotfile manager、pnpm 硬链接）：rewind 保留其内容不变，手动撤销会话的编辑
• 非你创建的链接：检查路径内容再信任（可能检查点后被替换）

配置警告¶

Claude Code 在启动时将这些消息写入 stderr（非对话内错误），报告读取但未应用的配置。

Workspace has not been trusted¶

Claude Code 发现项目 .claude/settings.json 或 .claude/settings.local.json 中的 permissions.allow 规则或 permissions.additionalDirectories 条目但未应用，因为允许规则需要工作区信任。 deny 和 ask 规则不受影响。

Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog...

处理：

• 在目录中运行 claude 并接受信任对话框（对话框列出被保留的规则并允许拒绝）
• 非交互模式（-p）无对话框时在 ~/.claude.json 中设置消息打印的 projects key 下的 hasTrustDialogAccepted: true

Is not matched by file permission checks¶

Claude Code 发现 Write、NotebookEdit、MultiEdit 或 Glob 权限规则带路径。 文件权限仅检查 Edit 和 Read 规则，不会查阅以其他文件工具命名的路径规则。规则被保留不变；警告指名规则、来源和替换写法。

Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

处理：

• 将 Write(path)、NotebookEdit(path) 和 MultiEdit(path) 规则替换为 Edit(path)（覆盖所有文件编辑工具）
• Glob(path) 规则替换为 Read(path)（--allowedTools 中除外，Claude Code 接受 Glob 无警告）
• 在警告指名的来源处修复
• 裸工具名规则（如 Write、Glob）保持不变（在工具级别匹配，不警告）
• 来源为 managed policy settings 时将警告转发给维护你的受管设置的人

响应质量似乎下降¶

如果 Claude 的回答似乎不如预期但无错误显示，原因通常是对话状态而非模型本身。 Claude Code 不会静默更换模型版本。它仅在三种情况下切换到备用模型：

• 配置了 --fallback-model 在可用性错误后接管（仅该轮，有记录通知）
• Amazon Bedrock 或 Google Cloud Agent Platform 启动检查发现默认模型不可用
• Fable 5 和 Opus 5 的自动模型回退将会话移至标记类别的备用模型（有记录通知）

下方模型选择检查可发现第二和第三种情况；第一种作为记录通知而非 /model 变更出现。

首先检查：

响应出错时回退（/rewind）通常比在线程中纠正更好。 按 Esc 两次或运行 /rewind 回退到错误轮次之前，重新措辞 prompt 并提供更多细节。在线程中纠正保留错误尝试在上下文中，可能锚定后续回答。参见检查点。

上述检查后质量仍不佳时运行 /feedback 描述预期 vs 实际。提交的反馈含对话记录，是 Anthropic 诊断真正退化的最快方式。

若 Claude 警告疑似 prompt injection 或因此拒绝请求，且被标记的文本是 Claude Code 自动添加的上下文（非文件/网络内容），运行 claude update 并重试。更新后仍出现则报告而非将标记内容粘回 prompt。

报告错误¶

本页未涵盖的组件错误参见相关指南：

• MCP 服务器连接或认证失败：MCP
• Hook 脚本失败或阻止工具：调试 hooks
• 安装期间权限被拒或文件系统错误：安装排错

若错误未在本页列出或建议的修复无效：

• 在 Claude Code 内运行 /feedback 发送记录和描述给 Anthropic（也可打开预填的 GitHub issue）。发送需要认证。Bedrock/Vertex/Foundry 等第三方提供商或无 Anthropic 凭据时，/feedback 保存本地归档可发给你的 Anthropic 客户代表
• 在 shell 中运行 claude doctor 进行安装只读诊断，或在 Claude Code 内运行 /doctor 查找和修复设置问题
• 检查 status.claude.com 查看活跃事件
• 搜索 GitHub 已有 issues