错误参考

查阅 Claude Code 运行时错误信息，了解每条信息的含义及修复方法。

本页列出了 Claude Code 显示的运行时错误及各自的恢复方法，以及在回复看起来不对但没有出现错误时应检查什么。关于诸如搭建期间 command not found 或 TLS 失败之类的安装错误，请参阅故障排查安装与登录。

这些错误和恢复命令适用于 CLI、桌面应用和网页版 Claude Code，因为这三者都是对同一个 Claude Code CLI 的包装。关于特定界面的问题，请参阅该界面页面上的故障排查部分。

查找你的错误

将你在终端中看到的信息与下面的小节匹配。

自动重试

Claude Code 会先重试临时性故障，再向你显示错误。服务器错误、过载响应、请求超时、临时的 429 限流，以及连接断开，都会以指数退避方式最多重试 10 次。从 v2.1.198 开始，这也覆盖了在任何可见输出流出之前、在一次回复过程中断开的连接：Claude Code 会用相同的退避策略重新发出该请求，该轮次会继续，而不是因连接错误而停止。从 v2.1.199 开始，当你用 claude.ai 订阅登录时，不带该方案配额响应头的临时 429 限流也会被重试；更早的版本只为 API 密钥和 Enterprise 登录重试它们。

有两类失败不会被重试，因为重试无法成功：

• 从 v2.1.199 开始，一次 TLS 证书校验失败（例如一个进行 TLS 拦截的代理、缺失的 NODE_EXTRA_CA_CERTS 证书包，或一个已过期的证书）会在第一次尝试时就失败，这样修复方法能立即显示出来，而不是等到完整的重试预算耗尽之后。请参阅SSL 证书错误。像握手超时这样的临时性 TLS 状况仍会重试。
• 从 v2.1.199 开始，当一次服务器错误发生在 Claude 已经流出可见输出之后，会保留这份部分回复，并附加一条不完整回复提示，而不是重试，因为重新运行该请求可能会让同样的工具被执行两次。更早的版本会丢弃这部分输出，并把整个轮次报告为一个错误。

重试期间，加载指示符会在一条错误标签之后显示一个 Retrying in Ns · attempt x/y 倒计时。对于你可以立即采取行动的失败——网络中断、TLS 握手失败，或触及了速率限制——该标签会标明第一次尝试给出的具体原因。对于其他错误，它最初会显示 API error。从 v2.1.198 开始，它会在第三次尝试时（或当 CLAUDE_CODE_MAX_RETRIES 允许的次数少于三次时，在最后一次尝试时）切换为具体原因；更早的版本只在最后一次尝试时切换。

从 v2.1.198 开始，重试期间通常的加载提示会被抑制。一旦错误原因被揭示，如果该失败是 529 过载，倒计时下方的这一行还会标明应去哪里检查服务状态：在 Anthropic API 上是 status.claude.com，在其他配置上则是信息中标明的服务商或网关主机。

如果在一次请求仍处于待处理状态期间，响应流 20 秒内没有收到任何数据，加载指示符会在任何重试开始之前显示 Waiting for API response · will retry in … · check your network。此时该请求还没有失败：这个倒计时会一直运行到 Claude Code 中止这个卡住的连接并重试的那一刻，因此一旦数据恢复或重试成功，该提示条就会自行清除。从 v2.1.185 开始这个阈值是 20 秒；更早的版本会在 10 秒后显示该提示条，措辞也不同。如果它在每次尝试中都重新出现，请把它当作一个网络问题处理。

当你在本页看到某个错误时，说明那些重试已经耗尽了，除非它属于不会被重试的那一类，例如证书校验失败。你可以用以下环境变量调整这个行为：

服务器错误

这些错误来自推理服务商，而不是你的账号或请求。在 Anthropic API 上，这意味着 Anthropic 的基础设施。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自定义网关上，则是指该服务商的基础设施。

API Error: 500 Internal server error

对于任何 5xx 响应，Claude Code 都会显示状态码和 API 的错误信息。以下示例展示了 Anthropic API 上的一次 500 响应：

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.

末尾这句话说明了应去哪里检查服务健康状况，因服务商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置会标明该服务商的服务状态。自定义的 ANTHROPIC_BASE_URL 会标明网关主机。

这表明 API 内部发生了意外故障。这不是由你的提示词、设置或账号导致的。

该怎么做：

• 查看 status.claude.com，或信息中标明的服务商状态页面，看是否有正在发生的事件
• 等一分钟，再次发送你的消息。你原来的消息仍在对话中，因此对于一条长提示词，你可以输入 try again，而不必重新粘贴整段内容。
• 如果错误持续出现、且没有发布相关事件，运行 /feedback，让 Anthropic 能根据你的请求详情进行调查。如果 /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.

末尾这句话因服务商而异，方式与上面的 500 错误相同。

一次 529 不是你的用量限制，不会计入你的配额。

该怎么做：

• 查看 status.claude.com，或信息中标明的服务商状态页面，看是否有容量提示
• 几分钟后再试
• 运行 /model 切换到另一个模型以继续工作，因为容量是按模型追踪的。当某个模型负载特别高时，Claude Code 会提示你这样做，例如 Opus is experiencing high load, please use /model to switch to Sonnet。

Request timed out

API 在连接截止时间之前没有响应。

Request timed out

这可能发生在高负载期间，或模型正在生成一份非常大的回复时。默认的请求超时时间是 10 分钟。

该怎么做：

• 重试该请求
• 对于长时间运行的任务，把工作拆分成更小的提示词
• 如果原因是较慢的网络或代理，按照自动重试中所述提高 API_TIMEOUT_MS
• 如果超时频繁发生、且你的网络在其他方面表现正常，请参阅下方的网络和连接错误

The response above may be incomplete

在 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 服务器错误。这个版本需要 Claude Code v2.1.199 或更高版本；之前的版本会丢弃这部分输出，并把整个轮次报告为错误。
• Connection closed mid-response：连接断开了。
• Response stalled mid-stream：该流停止发送数据了。

该怎么做：

• 阅读已经流出的回复。没有任何内容丢失，但最后几句话或工具调用可能缺失。
• 回复 continue，让 Claude 从中断处继续
• 如果同样的错误出现在任何可见输出之前，Claude Code 会重试该请求，而不是将其定稿。请参阅自动重试。

Auto mode cannot determine the safety of an action

自动模式用来对操作分类的模型无法给出决定，因此自动模式没有自动批准该操作。你看到的信息取决于分类器失败的原因。

在你工作目录内部的读取、搜索和编辑会跳过分类器，因此在以下所有情况下都会继续正常工作。

当分类器模型过载时：

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

该怎么做：

• 几秒后重试；Claude 会看到同样的信息，通常会自行重试
• 如果重试反复失败，先继续做只读的任务，稍后再回来处理这个被阻塞的操作
• 这是暂时性的，与自动模式的适用性无关；你不需要更改设置

当分类器返回了一个无法解析的响应时：

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 — it isn't about the action itself — run with --debug for details

该怎么做：

• 这不是针对你操作的一个决定。对话中已有的内容，在自动模式将该对话发给分类器时，触发了 API 上的一个安全过滤器
• 重试无济于事；同样的对话内容会再次触发该过滤器
• 切换到一个不同的权限模式，这样在收到提示时你就可以批准该操作，或者在不包含触发内容的情况下开始一个全新对话

当对话已经增长到超出分类器的上下文窗口时：

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

在交互式会话中，自动模式会为该操作回退到一个正常的权限提示，让你手动批准或拒绝它。在非交互模式中，该次运行会中止，因为该记录只会不断增长，重试无法成功。

该怎么做：

• 在出现的提示中批准或拒绝该操作
• 运行 /compact 缩减对话大小，让后续操作能再次容纳在分类器窗口内

Agent terminated early due to an API error

一个子智能体的 API 请求彻底失败了，例如因为达到了用量限制，或服务器错误的重试次数耗尽了，因此该子智能体在完成任务之前就停止了。这条信息需要 Claude Code v2.1.199 或更高版本；在那之前，该 API 错误文本会被当作该子智能体的结果返回给 Claude。

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

该怎么做：

• 把冒号后的错误详情与本页相应的章节对照，例如用量限制或服务器错误，并遵循那一节的步骤
• 一旦底层错误消失，让 Claude 重试该任务，或恢复该子智能体

当速率限制、过载或服务器错误中断了一个已经产生文本输出的前台子智能体时，Claude 会收到那部分输出，并标记为不完整，而不是这个错误。一个只有工具调用作为输出的子智能体也会遇到这个错误；在 v2.1.199 中，这种情况会改为返回一个空的部分结果。请参阅子智能体中的 API 错误。

用量限制

这些错误意味着与你账号或方案相关联的一项配额已经用完。它们与影响所有人的服务器错误不同。

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

Claude Code 会阻止进一步的请求，直到信息中显示的重置时间。

该怎么做：

• 等到信息中显示的重置时间
• 运行 /usage 查看你方案的限额及其重置时间
• 运行 /usage-credits，在 Pro 和 Max 上购买额外用量，或在 Team 和 Enterprise 上向你的管理员申请。关于计费方式，请参阅付费方案的额外用量。
• 要升级你的方案以获得更高的基础限额，请参阅 claude.com/pricing

要在触及限额之前查看你剩余的额度，可以把 rate_limits 字段加入一个自定义状态栏，或在桌面应用中点击模型选择器旁的用量环。

Usage credits required for 1M context

所选模型使用了 100 万 Token 的扩展上下文窗口，而你的方案只能通过用量额度获得它。

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

这是一项权限检查，不是配额耗尽。即使你的会话和每周额度仍有余量，它也会出现。关于哪些方案直接包含 100 万上下文、哪些需要用量额度，请参阅扩展上下文。

当这个错误因为上下文增长超过 20 万 Token 而在对话中途出现时，Claude Code 会自动把对话压缩回标准上下文限制以内，并在之后保持会话处于该限制内，因此无需任何操作。在 v2.1.172 之前的版本上，这个错误会在之后每一次请求（包括 /compact）中重复出现；在这些版本上，运行 /clear 即可恢复。下面的步骤适用于你显式选择了一个 [1m] 模型的情况。

该怎么做：

• 运行 /model 并选择不带 [1m] 后缀的变体，回退到标准上下文窗口
• 运行 /usage-credits，在 Pro 和 Max 上为 100 万变体开启按量计费，或在 Team 和 Enterprise 上向你的管理员申请
• 如果 /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 通过是否携带真正限额响应会带有的统一配额响应头，来区分这类情况和你的方案限额。从 v2.1.199 开始，无论你以哪种方式进行身份验证，这都会在显示之前先自动重试并配合退避策略。在更早的版本上，用 claude.ai 订阅登录的会话在第一次出现时就会让该轮次失败；只有 API 密钥和 Enterprise 登录会重试它。

该怎么做：

• 稍等片刻再试
• 如果持续出现，查看 status.claude.com

Request rejected (429)

你已经触及了为你的 API 密钥、Amazon Bedrock 项目或 Google Cloud 项目配置的速率限制。

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

末尾这句话说明了应去哪里检查服务健康状况，因服务商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置会标明该服务商的服务状态，而不是 Anthropic 的状态页面。自定义的 ANTHROPIC_BASE_URL 会标明网关主机。

该怎么做：

• 运行 /status，确认当前生效的凭据是你预期的那个。环境中残留的一个 ANTHROPIC_API_KEY，可能会让请求走一个低层级的密钥，而不是你的订阅。
• 检查你服务商控制台中的当前限额，如需更高等级请申请
• 对于 Anthropic API 密钥，关于层级如何运作以及如何设置每工作区的上限，请参阅速率限制参考文档
• 降低并发度：调低 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY，避免运行大量并行子智能体，或对高频脚本化运行用 /model 切换到更小的模型

Credit balance is too low

你的 Console 组织已用尽预付额度。

Credit balance is too low

该怎么做：

• 在 platform.claude.com/settings/billing 添加额度，并考虑在那里启用自动充值，以便余额在归零之前得到补充
• 如果你有 Pro、Max、Team 或 Enterprise 方案，用 /login 切换到订阅身份验证
• 在 Console 中为各工作区设置花费上限，防止单个项目耗尽组织余额。请参阅有效管理成本。

身份验证错误

这些错误意味着 Claude Code 无法向 API 证明你的身份。随时运行 /status，即可查看当前生效的是哪个凭据。

Not logged in

该会话没有可用的有效凭据。

Not logged in · Please run /login

该怎么做：

• 运行 /login，用你的 Claude 订阅或 Console 账号进行身份验证
• 如果你原本期望用一个环境变量进行身份验证，请确认在你启动 claude 的那个 shell 中已经设置并导出了 ANTHROPIC_API_KEY
• 对于无法交互式登录的 CI 或自动化场景，配置一个能在启动时获取密钥的 apiKeyHelper 脚本
• 关于当多个凭据同时存在时 Claude Code 使用哪一个，请参阅身份验证优先级

如果你被反复要求登录，请参阅未登录或令牌过期了解系统时钟和 macOS 密钥链方面的修复方法。

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. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

在 v2.1.174 之前，一个分配给闲置预初始化工作进程的后台或云端会话，即使已配置了有效凭据，也可能以这种方式失败。升级即可恢复。在当前版本上，这个错误意味着该工作进程本身没有获取到任何凭据。

该怎么做：

• 如果这出现在一个后台或云端会话中、且你的凭据已经配置好了，请升级到 v2.1.174 或更高版本
• 确认 ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN，或你云服务商的凭据，已经在启动该工作进程的环境中设置，而不仅仅是在你的交互式 shell 中
• 对于 Agent SDK，请参阅身份验证搭建
• 在同一环境中的一个交互式会话中运行 /status，确认解析出的是哪个凭据来源

Invalid API key

ANTHROPIC_API_KEY 环境变量或 apiKeyHelper 脚本返回了一个 API 拒绝的密钥。

Invalid API key · Fix external API key

该怎么做：

• 检查是否有拼写错误，并在 Console 中确认该密钥没有被撤销
• 在同一个 shell 中运行 env | grep ANTHROPIC。像 direnv、dotenv shell 插件和 IDE 终端这样的工具，可能会在你没有显式设置的情况下，从项目中的一个 .env 文件加载一个过时的密钥。
• 取消设置 ANTHROPIC_API_KEY，运行 /login 改用订阅身份验证
• 如果该密钥来自一个 apiKeyHelper 脚本，直接运行该脚本，确认它在 stdout 中打印了一个有效的密钥
• 运行 /status 确认 Claude Code 实际使用的是哪个凭据来源

This organization has been disabled

一个来自已禁用 Console 组织的过时 ANTHROPIC_API_KEY，正在覆盖你的订阅登录。

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials
API Error: 400 ... This organization has been disabled.

环境变量的优先级高于 /login，因此即使你有一个正常工作的 Pro 或 Max 订阅，在你 shell 配置文件中导出的、或从一个 .env 文件加载的密钥仍会被使用。在非交互模式（-p）下，只要存在该密钥，就总会使用它。

该怎么做：

• 在当前 shell 中取消设置 ANTHROPIC_API_KEY，并从你的 shell 配置文件中移除它，然后重新启动 claude
• 之后运行 /status，确认当前生效的凭据是你的订阅
• 如果没有设置任何环境变量、且错误依然存在，说明那个被禁用的组织正是与你的 /login 绑定的那个。请联系支持团队，或用另一个账号登录。

Your organization has disabled API key authentication

这条信息需要 Claude Code v2.1.169 或更高版本。你 Console 组织的管理员关闭了 API 密钥身份验证，因此 API 拒绝了 Claude Code 发送的密钥。· 之后的恢复提示因密钥来源而异：

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

环境变量和 apiKeyHelper 的优先级高于 /login，因此只运行 /login 而不处理这两者中仍在生效的一个，是无济于事的。请参阅身份验证优先级。

该怎么做：

• 如果信息中提到了 ANTHROPIC_API_KEY，请在当前 shell 中取消设置它，并从你的 shell 配置文件或 .env 文件中移除它，然后重新启动 claude
• 如果信息中提到了 apiKeyHelper，请从你的 settings.json 中移除 apiKeyHelper 设置
• 运行 /login，用你的 claude.ai 账号登录
• 之后运行 /status，确认当前生效的凭据是你的订阅，而不是某个 API 密钥
• 如果你的自动化流程需要 API 密钥身份验证，请让你的组织管理员在 Console 中重新启用它

Your organization has disabled Claude subscription access

你 Claude 组织不允许用订阅登录方式登录 Claude Code。用同一个账号再次运行 /login 会返回同样的错误。

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

这是一项服务端的组织设置，因此无法通过本地设置、环境变量或 CLI 标志覆盖。

Agent SDK 和 -p 非交互模式会将其呈现为 oauth_org_not_allowed 错误码。

该怎么做：

• 请你的管理员为你的组织启用 Claude Code 访问权限
• 改用一个 Console API 密钥进行身份验证，而不是你的订阅。搭建方法请参阅Claude Console 身份验证。
• 如果你是管理员、却没有看到启用访问权限的选项，请联系Anthropic 支持团队

Routines are disabled by your organization's policy

你 Team 或 Enterprise 组织中的一位 Owner 在组织级别关闭了例行任务。当你尝试创建或运行一个例行任务（包括通过 /schedule 和 claude.ai/code 上的例行任务界面）时，会出现这个错误。

Routines are disabled by your organization's policy.

这是一项服务端设置，因此无法通过本地设置、环境变量或 CLI 标志覆盖。

该怎么做：

• 请你组织中的一位 Owner 在 claude.ai/admin-settings/claude-code 启用Routines 开关
• 对于不需要组织级例行任务的一次性定时工作，请参阅定时任务

Remote Control requires the Anthropic API

该会话没有直接与 Anthropic API 通信，因此没有 claude.ai 后端可供远程控制配对。

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

这会出现在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。从 v2.1.196 开始，当 ANTHROPIC_BASE_URL 指向一个不是 api.anthropic.com 的主机（例如一个LLM 网关或代理）时，即使你用 claude.ai 登录，它也会出现。

该怎么做：

• 取消设置 ANTHROPIC_BASE_URL 并重启该会话，或从一个直接与 Anthropic API 通信的会话启动远程控制
• 关于这个以及其他远程控制启动信息，请参阅远程控制故障排查

OAuth token revoked or expired

你已保存的登录状态不再有效。令牌被撤销意味着你在所有地方都退出了登录，或某位管理员移除了访问权限；令牌过期意味着自动刷新在会话中途失败了。

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

该怎么做：

• 运行 /login 重新登录
• 如果重新身份验证后该错误在同一会话内再次出现，请先运行 /logout 完全清除已存储的令牌，然后再运行 /login
• 关于跨多次启动反复被要求登录的问题，请参阅故障排查中关于系统时钟和 macOS 密钥链的检查方法
• 关于其他失败（包括 403 Forbidden 和 OAuth 浏览器问题），请参阅登录与身份验证

OAuth scope requirement

已存储的令牌早于某个新功能所需的权限作用域。你最常从 /usage 和状态栏的用量指示符中看到这个：

OAuth token does not meet scope requirement: user:profile

该怎么做：

• 运行 /login 获取一个带有当前作用域的新令牌。你不需要先退出登录。

AWS credentials expired or invalid

这条信息需要 Claude Code v2.1.198 或更高版本，只在你设置文件中设置了 awsAuthRefresh 时才会出现。你的 AWS 会话令牌已过期或被拒绝，Claude Code 已经运行过的自动刷新没有产生一个 API 能接受的凭据。它出现在来自AWS 上的 Claude 平台或Mantle 端点的一次 401 响应上，这是这些服务商报告过期安全令牌的方式。

信息中间的操作提示会标明你设置中的 awsAuthRefresh 命令，因此会有所不同。稳定不变的部分是开头的 AWS credentials expired or invalid：

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

在没有配置 awsAuthRefresh 的情况下，同样的 401 会改为显示通用的 Please run /login 信息，而这无法刷新 AWS 凭据。

该怎么做：

• 在另一个终端中运行信息中标明的 awsAuthRefresh 命令（例如 aws sso login --profile myprofile），完成浏览器登录，然后重试
• 在一个交互式会话中，运行 /login，选择3rd-party platform，然后在 Using 3rd-party platforms 下选择Claude Platform on AWS · refresh credentials，即可在不重启 Claude Code 的情况下运行同一个命令。请参阅配置 AWS 凭据
• 如果刷新命令成功后错误仍反复出现，请在同一个 shell 和 profile 下用 aws sts get-caller-identity 确认该身份在 Claude Code 之外是有效的

AWS authentication failed

这条信息需要 Claude Code v2.1.198 或更高版本，只在你设置文件中设置了 awsAuthRefresh 时才会出现。你的 AWS 服务商返回了一个 403，或Amazon Bedrock 返回了一个 401。

Claude Code 无法判断你遇到的具体是哪种原因。Amazon Bedrock 会把一个过期的安全令牌报告为 403，但 403 同样是它报告授权拒绝的方式，例如因缺少某个 IAM 权限而产生的 AccessDeniedException，或某个模型未对你的账号启用。

来自 Amazon Bedrock 的 401 也会落在这里，而不是AWS 凭据已过期或无效下，因为 Amazon Bedrock 不会把过期令牌报告为 401。来自那个端点的 401 通常来自请求路径中的其他环节，例如一个企业代理。

刷新凭据能修复一个过期的令牌，但无法修复其他原因，因此这条信息会同时提供两种方案：

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 authentication failed。

该怎么做：

• 运行信息中标明的 awsAuthRefresh 命令，或 aws sso login，以防原因是一个过期的凭据
• 如果你的凭据是最新的，请确认IAM 配置中的权限已附加到你正在使用的身份上，且所选模型已针对你的账号和区域启用
• 运行 aws sts get-caller-identity，确认你的请求使用的是哪个身份；一个过时的 AWS_PROFILE 或默认 profile 是权限不匹配的常见原因

网络与连接错误

这些错误意味着来自 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，确认你能访问该 API 主机。在 Windows PowerShell 中，使用 curl.exe -I https://api.anthropic.com，以避免使用内置的 Invoke-WebRequest 别名。
• 如果你在一个企业代理之后，请在启动 Claude Code 之前设置 HTTPS_PROXY，并参阅网络配置
• 如果你通过一个 LLM 网关或中继路由，请将 ANTHROPIC_BASE_URL 设为它的地址。搭建方法请参阅将 Claude Code 连接到 LLM 网关。
• 确保你的防火墙允许网络访问要求中列出的主机
• 间歇性的失败会被自动重试；持续性的失败则指向一个本地网络问题

如果 curl 成功了，但 Claude Code 仍然失败，原因通常出在运行时和网络之间，而不是网络本身：

• 在 Linux 和 WSL 上，检查 /etc/resolv.conf 中是否有一个无法访问的名称服务器。WSL 尤其可能从主机继承一个损坏的解析器。
• 在 macOS 上，一个已断开或已卸载的 VPN 客户端，可能留下一个隧道接口或路由规则。请检查 ifconfig 中是否有残留的 utun 接口，并在系统设置中移除该 VPN 的网络扩展。
• Docker Desktop 和类似的容器运行时可能会拦截出站流量。退出它们再重试，以排除这种可能性。

SSL certificate errors

你网络上的一个代理或安全设备，正在用它自己的证书拦截 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

从 v2.1.199 开始，证书校验失败不会被重试，因此这个错误会在第一次尝试时就出现，而不是在完整的重试预算耗尽之后。更早的版本会先重试几分钟再显示它。像握手超时这样的临时性 TLS 状况仍会重试。

在 /login 和启动时的连接检查期间，同样的失败会连同 OpenSSL 错误码和修复方法一起报告：

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

该怎么做：

• 导出你组织的 CA 证书包，用 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 让 Claude Code 指向它
• 完整的搭建说明请参阅网络配置
• 不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0，它会完全关闭证书校验

Host not allowed in a cloud session

一次从云端会话或例行任务发出的出站 HTTP 请求，被该环境的网络策略阻止了。

HTTP 403
x-deny-reason: host_not_allowed

你也可能会看到一个与目标真实证书不匹配的 TLS 证书。该云环境会通过一个执行网络策略的代理路由出站流量，因此证书不匹配意味着该代理终止了这个连接，而不是目标本身。

这不是一个客户端侧的网络问题。云端会话和例行任务运行在一个沙箱环境内部，其出站流量会按该环境的允许列表进行过滤。Default 环境使用Trusted 访问级别，允许默认允许列表中的软件包注册表、云服务商 API、容器注册表和常见开发域名，但会阻止其他一切。

该怎么做：

• 打开该例行任务进行编辑，或启动一个云端会话。点击显示你环境名称（例如Default）的云图标，打开选择器。将鼠标悬停在你的环境上，点击设置图标。
• 在Update cloud environment 对话框中，将Network access 从Trusted 改为Custom，然后将被阻止的域名添加到Allowed domains。每行输入一个域名。勾选Also include default list of common package managers，即可在你自定义域名之外保留默认允许列表。如果你想要不受限制的访问，请改选Full。
• 点击Save changes。下一次运行会使用更新后的允许列表。

关于访问级别和默认允许列表，请参阅网络访问。本地 CLI 会话不受这项策略影响。

Couldn't reconnect to your Remote Control session

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

用 claude --resume 或 claude --continue 恢复会话，会重新连接到该对话中记录的远程控制会话。这条信息意味着重新连接因为某个可能是临时性的原因（例如网络中断或服务器错误）失败了，因此 Claude Code 无法确认那个远程会话是否仍然存在。你的本地会话会在没有远程控制的情况下继续运行。

该怎么做：

• 运行 /remote-control 重试连接
• 不带 --resume 启动 Claude Code，以创建一个新的远程控制会话
• 关于其他远程控制启动信息，请参阅远程控制故障排查

当服务器确认之前的会话已不存在时，你不会看到这条信息；在这种情况下，Claude Code 会创建一个新的。在 v2.1.200 之前，任何重连失败都会创建一个新的远程控制会话，导致 claude.ai/code 的会话列表中留下多余的会话。

请求错误

这些错误与你请求的内容有关。大多数是 API 拒绝该请求后返回的；少数是 Claude Code 在发送任何请求之前就在本地产生的。

Prompt is too long

对话加上附加文件超过了该模型的上下文窗口。

Prompt is too long

该怎么做：

• 运行 /compact 摘要较早的轮次以释放空间，或运行 /clear 重新开始
• 运行 /context 查看占用该窗口的内容细分：系统提示词、工具、记忆文件和消息
• 用 /mcp disable <name> 禁用你没在使用的 MCP 服务器，把它们的工具定义从上下文中移除
• 精简大型 CLAUDE.md 记忆文件，或把指令移到只在相关时才加载的路径限定规则中
• 子智能体会继承父会话的每一个 MCP 工具定义，这可能在第一轮之前就填满它们的上下文窗口。在生成子智能体之前，先禁用你没在使用的 MCP 服务器。
• 自动压缩默认开启，通常能防止这个错误。如果你设置了 DISABLE_AUTO_COMPACT，请重新启用它，或在窗口填满之前手动运行 /compact。

关于上下文如何被填满的交互式视图，请参阅探索上下文窗口。

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.

这可能发生在自动压缩触发那一刻窗口已经填满时，或你在看到 Prompt is too long 之后运行 /compact 时。

该怎么做：

• 按两次 Esc 打开消息列表，往回退几轮。这会把最近的消息从上下文中丢弃。然后再次运行 /compact。
• 如果往回退不足以释放足够空间，运行 /clear 开始一个全新会话。你之前的对话会被保留，可以用 /resume 重新打开。

Request too large

原始请求体在分词之前就超过了 API 的字节限制，通常是因为粘贴了一个大文件或附件。

Request too large (max 30 MB). Double press esc to go back and remove or shrink the attached content.

这是对 HTTP 请求的一项大小限制，与上下文窗口限制是分开的。

该怎么做：

• 按两次 Esc，退回到添加了过大内容的那个轮次之前
• 用路径引用大文件，而不是粘贴其内容，这样 Claude 就可以分块读取它们
• 关于图片，请参阅下面的图片过大

Image was too large

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

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

Claude Code 会用一个文本占位符替换这个无法处理的图片并重试，因此后续消息会成功。在 2.1.142 之前的版本上，一张粘贴的图片可能会留在对话中，并在之后每条消息上重复同样的错误。要在这些版本上恢复，请按两次 Esc，退回到添加该图片的轮次之前。

该怎么做：

• 在粘贴之前调整图片大小。API 对单张图片最长边最多接受 8000 像素，当上下文中有多张图片时最多接受 2000 像素。
• 对相关区域截一张更紧凑的截图，而不是整个屏幕

Unable to resize image

Claude Code 在把一张附加图片发送给 API 之前，无法对其进行降采样。

Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. Please resize the image to reduce its pixel dimensions.
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. Please resize the image manually or use a smaller image.
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.

Claude Code 通常会自动调整大图片的尺寸。这些错误意味着原生图像处理器加载失败或返回了一个错误，因此该图片无法被调整到符合 API 限制的尺寸。

该怎么做：

• 如果信息要求你转换该图片，请将其转换为 PNG、JPEG、GIF 或 WebP，然后重新附加。对于这些格式，Claude Code 可以在没有图像处理器的情况下验证尺寸。
• 如果信息报告了一个尺寸或大小限制，请在附加之前把该图片调整或重新压缩到该限制以下。

PDF errors

你附加的 PDF 无法被处理。

PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.
PDF is password protected. Try removing protection or extracting text first.
The PDF file was not valid. Try converting to a different format first.

该怎么做：

• 对于过大的 PDF，可以让 Claude 用 Read 工具读取某个页码范围，而不是附加整个文件，或者用像 pdftotext 这样的工具提取文本，并用路径引用输出文件
• 对于受保护或无效的 PDF，请移除密码，或从其来源应用重新导出该文件，然后重试

Extra inputs are not permitted

位于 Claude Code 和 API 之间的一个代理或 LLM 网关剥离了 anthropic-beta 请求头，因此该 API 拒绝了依赖它的字段。

API Error: 400 ... Extra inputs are not permitted ... context_management
API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples
API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

Claude Code 会发送诸如 context_management、effort 和工具 input_examples 这样的 beta 专属字段，同时附带一个启用它们的 anthropic-beta 请求头。当某个网关转发了请求体、却丢弃了这个请求头时，API 就会看到它不认识的字段。

该怎么做：

• 配置你的网关转发 anthropic-beta 请求头。关于网关必须转发哪些内容，请参阅特性透传。
• 作为一种备选方案，在启动前设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。这会关闭需要 beta 请求头的功能，让请求能通过一个无法转发它的网关。

There's an issue with the selected model

配置的模型名称未被识别，或你的账号没有访问它的权限。从 v2.1.160 开始，末尾的提示（这里展示的是其交互式形式）会因界面不同而不同。

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。在这个界面上，错误文本会显示 Run --model。
• Agent SDK：错误文本会省略这个提示，因为模型是通过程序设置的。请在 TypeScript 中设置Options 上的 model，或在 Python 中设置 ClaudeAgentOptions(model=...)，并处理结构化的 model_not_found 错误，以呈现你自己的重试或模型选择器。
• 使用像 sonnet 或 opus 这样的别名，而不是完整的带版本号 ID。别名会解析到一个维护中的默认值，因此不会过时。请参阅模型配置。
• 如果 CLI 中反复出现错误的模型，说明某处设置了一个过时的 ID。请按优先级顺序检查：--model 标志、ANTHROPIC_MODEL 环境变量，然后是 .claude/settings.local.json、你项目的 .claude/settings.json，以及 ~/.claude/settings.json 中的 model 字段。移除那个过时的值，Claude Code 就会回退到你账号的默认值。
• 对于 Google Cloud 的 Agent Platform 部署，请参阅Google Cloud 的 Agent Platform 故障排查。

Model is not a recognized model id

你传给模型切换的字符串既不是一个模型别名，也不是这个 Claude Code 版本认识的模型 ID，也不是一个以 claude- 开头的 ID。常见原因是 ID 中有拼写错误、使用了像 Sonnet 5 这样的显示名称（而期望的是 ID claude-sonnet-5），或使用了只有更新版本的 Claude Code 才认识的别名。Claude Code 会立即拒绝这次切换。在 v2.1.200 之前，Claude Code 会保存这个字符串，并在下一次请求时以所选模型存在问题失败。

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

末尾的提示会标明最接近匹配的别名或模型 ID。当没有足够接近的匹配时，它会改为显示 Run /model to see available models.。

Claude Code 会在请求切换的那一刻、在任何 API 请求发出之前，就在本地产生这个错误。它适用于通过 Agent SDK 的 setModel() 方法设置模型，或由一个像桌面应用这样代你运行 Claude Code CLI 的应用设置模型的情况。

该怎么做：

• 不带参数运行 /model 打开选择器，从你账号可用的模型中选择，然后传入那里显示的别名或 ID
• 如果你使用的别名是较新版本的 Claude Code 才支持的，运行 claude update。一个以 claude- 开头的完整 ID，即使该模型比你的 Claude Code 版本更新，也能通过这个检查，因此对于这些情况不需要升级。
• 在 v2.1.200 之前保存的一个模型不会被这个检查修复。如果一个过时的值反复出现，请从所选模型存在问题中列出的位置移除它。
• 这个检查只在 Anthropic API 上运行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、AWS 上的 Claude 平台，以及位于LLM 网关或自定义 ANTHROPIC_BASE_URL 之后时，你的服务商或网关定义模型名称，因此 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。已存储的令牌反映的是你登录那一刻的方案，因此在网页上升级不会立即在已有会话中生效，直到你重新进行身份验证。
• 关于每个方案包含哪些模型，请参阅 claude.com/pricing

Model is restricted by your organization's settings

你的组织管理员在 claude.ai 管理控制台中禁用了这个模型，或它被统一管理设置中的 availableModels 允许列表排除了。当受限模型是通过 --model、ANTHROPIC_MODEL 或 model 设置指定时，Claude Code 会替换为一个允许的模型并继续。为一个受限模型输入 /model <name> 会被拒绝，提示 Run /model to choose a different model.，该会话会保持其当前模型。

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

Claude Code 会把 opus、sonnet、haiku 或 fable 这样的模型系列别名，当作对该系列的请求，而不是对其最新版本的请求。在 Anthropic API 和AWS 上的 Claude 平台上，一个受限的系列别名会解析为该系列中你组织和 availableModels 允许列表所允许的最新版本，替换提示会标明那个版本。只有当该系列的每个版本都受限时，Claude Code 才会拒绝 /model <alias>。在 v2.1.205 之前，一个系列别名仅根据其最新版本被替换或拒绝，即使该系列中一个较旧的版本是被允许的。

该怎么做：

• 运行 /model，从你组织允许的模型中选择。受限模型会从选择器中隐藏。
• 如果受限模型是在 --model、ANTHROPIC_MODEL，或某个设置文件的 model 字段中设置的，请移除或更新那个值，这样该提示就不会在每次启动时重复出现
• 如果你需要访问该受限模型，请让你的组织管理员启用它。请参阅组织模型限制。

thinking.type.enabled is not supported for this model

你的 Claude Code 版本低于 Sonnet 5、Opus 4.8 或 Opus 4.7 所需的最低版本。该 CLI 发送了一个该模型已不再接受的思考配置。

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 并重启 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本
• 如果你无法升级，运行 /model，改选 Opus 4.6 或 Sonnet 4.6
• 如果你在 Agent SDK 中遇到这个问题，请改为升级该 SDK 软件包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本，以及 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本

Thinking budget exceeds output limit

配置的扩展思考预算超过了最大回复长度，因此没有剩余空间留给实际答案。

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

Claude Code 会在 Anthropic API 上自动调整这些值。当 MAX_THINKING_TOKENS 被设置得比服务商的输出限制更高，或计划模式提高了思考预算时，你通常会在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到这个错误。

该怎么做：

• 降低 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 或 Opus 4.8，请先运行 claude update。v2.1.156 之前的版本可能在正常工具使用期间触发这个错误，/rewind 也无法清除它。
• 运行 /rewind，或按两次 Esc，退回到损坏轮次之前的一个检查点，然后从那里继续。关于检查点的创建和恢复方式，请参阅检查点。

Usage Policy refusal

因为对话中的内容触发了一次使用政策检查，API 拒绝了响应。该信息包含一个请求 ID，如果你认为这次拒绝有误，可以引用它联系支持团队。

API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

这项检查评估的是完整对话，而不仅仅是你最新的提示词，因此在同一会话中发送新消息通常会再次触发同样的拒绝。用 --continue 或 --resume 退出并重新打开该会话后同样如此，因为磁盘上的记录仍然包含触发内容。在Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，这条信息也涵盖了模型安全措施标记为网络安全话题的请求。请参阅安全措施标记了一个网络安全话题。

该怎么做：

• 按两次 Esc，或运行 /rewind，退回到触发这次拒绝的轮次之前的一个检查点，然后改写措辞或采取不同的方法。请参阅检查点。
• 如果你无法确定是哪个轮次导致的，运行 /clear，在同一个项目中开始一个全新对话。你之前的对话会保存在磁盘上，仍可通过 /resume 访问。
• 在无法使用 rewind 的非交互模式（-p）下，在一个不带 --continue 的新会话中用改写后的提示词重试。策略检查因模型而异，因此在某些情况下用 --model 切换到不同的模型也可能解决这次拒绝。

Safety measures flagged a cybersecurity topic

该模型的安全措施将对话中的内容标记为一个网络安全话题。该信息会标明是哪个模型标记了这个请求：

API Error: Opus 4.8 has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude.

If you were not engaging in a cybersecurity topic, please send feedback via /feedback.

该信息链接到网络验证计划，为合法的网络安全工作授予访问权限。这项保护措施本身是服务端的，早于 v2.1.203；这个版本只更改了信息的措辞和它链接的页面。

你看到的内容取决于你的服务商和模式：

• 在Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，一次网络安全标记会改为产生使用政策拒绝信息。
• 非交互模式会省略 /feedback 那句话。

在 v2.1.203 之前，该信息写作 <model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:，后面附一个豁免申请表链接。

该怎么做：

• 如果你的工作确实需要这类内容，请通过网络验证计划申请访问权限
• 如果你的请求与网络安全话题无关，运行 /feedback 报告这次误判
• 要在同一会话中继续工作，按两次 Esc 或运行 /rewind，退回到触发这次标记的轮次之前的一个检查点，然后采取不同的方法。请参阅检查点。

安装错误

这些错误出现在通过安装脚本、claude install 或 claude update 安装或更新 Claude Code 期间。关于搭建期间的 command not found、PATH、权限和 TLS 问题，请参阅故障排查安装与登录。

Installation was killed before it could finish

安装脚本会在 claude install 步骤被某个信号终止时报告。在 Linux 上，退出码 137 意味着该进程收到了 SIGKILL，在内存不足的主机上，这通常是内核的内存溢出（OOM）杀手所致。该脚本会打印这个说明并以代码 137 退出：

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，该脚本会打印 Installation was killed before it could finish (exit code <N>)，附上实际的退出码，并省略内存溢出的说明。这条信息来自 macOS 和 Linux 使用的安装脚本，也涵盖 WSL 内部的安装；原生的 Windows 安装脚本从不打印它。在 v2.1.200 之前，该脚本只会以 shell 自身裸露的 Killed 那一行退出。

该怎么做：

• 停止其他进程以释放内存，然后重新运行安装程序
• 添加交换空间，或迁移到更大的实例。关于交换文件的具体命令，请参阅在低内存 Linux 服务器上安装被终止。

The connection dropped while downloading the update

在 claude install、claude update 或自动更新程序获取 Claude Code 二进制文件期间，到下载服务器的连接关闭了，重试也没能恢复。当连接断开、传输卡住，或下载的文件校验和失败时，Claude Code 会重试该下载，总共最多尝试三次。一个已完成的 HTTP 错误（例如 404）不会被重试，因为服务器已经给出了回应。在 v2.1.202 之前，单次连接断开会立即以裸露的错误 aborted 让该下载失败，而不会重试。

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

括号中的文本标明了是哪次尝试失败以及底层的网络错误。claude update 会在 stderr 上、在这条信息之前显示 Error: Failed to install native update。

一次保持连接、但在 10 分钟内没有完成的下载，会改为以 Download timed out: exceeded the total deadline 失败。Claude Code 不会重试一次超时的下载，因为一个太慢、无法在截止时间内完成的连接，立即重试同样无法完成。以下步骤适用于这两条信息。在 v2.1.205 之前，同样的 10 分钟截止时间会被报告为 HTTP 客户端的通用信息 timeout of 600000ms exceeded。

常见原因是某个代理或网关在一次长传输完成之前就将其关闭。Claude Code 二进制文件是一个较大的下载，因此一个通常不会影响普通 API 流量的代理连接限制，仍可能中断它。

该怎么做：

• 再次运行 claude update。在一个本来健康的网络上，下载通常会在下一次运行时成功。对于超时信息，请从一个更快或限流较少的网络再运行一次。
• 如果你的网络需要代理，请在运行安装程序或 claude update 之前设置 HTTPS_PROXY。请参阅检查网络连接。
• 如果一个企业代理持续关闭这个传输，请让你的网络团队允许来自 downloads.claude.ai 的完整下载。请参阅网络访问要求。
• 在你的 shell 中运行 claude doctor 获取安装诊断信息

命令行错误

这些错误来自 claude 命令行及其子命令。Claude Code 会在运行你的提示词或发送任何 API 请求之前打印它们。

Conflict between --bg and --print

这条信息需要 Claude Code v2.1.198 或更高版本。你在同一次 claude 调用中同时使用了 --bg 和 -p 或 --print。--bg 会启动一个你之后用 claude agents 接入的后台会话，而 --print 以非交互方式运行，永远不会启动 claude agents 所能接入的那种交互式会话。在 v2.1.198 之前，这种组合会悄悄创建一个永远无法被接入的后台任务。

--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

该怎么做：

• 去掉 -p 或 --print。--bg 把提示词当作其位置参数，因此 claude --bg "<task>" 就是完整的命令。请参阅从你的 shell 分派新智能体。
• 要以非交互方式运行提示词并打印结果，而不是创建一个后台会话，去掉 --bg，运行 claude -p "<task>"

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

你在非交互模式中传给 --json-schema 的模式未能通过 JSON Schema 编译，因此 claude 会以退出码 1 退出，而不会运行该提示词。在 v2.1.205 之前，一份无效的模式会不带任何错误地产生非结构化输出，任何使用 format 关键字的模式都会被视为无效。

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

第二个冒号之后的文本是校验器的诊断信息，标明了失败的关键字或位置。使用 format 关键字的模式（例如 "format": "email"）是有效的：Claude Code 会把 format 当作一个标注接受下来，不会强制执行它。

Claude Code 会在模式编译之前运行两项检查：它会用 Error: --json-schema is not valid JSON 拒绝一个无法解析为 JSON 的值，并用 Error: --json-schema must be a JSON object 拒绝一个有效的、但不是对象的 JSON。

该怎么做：

• 修复诊断信息中指出的那部分模式，然后重新运行该命令
• 如果诊断信息是 schema too large，请减少该模式的嵌套层级和 $ref 复用
• 关于一份能正常工作的模式和命令，请参阅获得结构化输出

Could not import a server from Claude Desktop

Claude Code 无法添加你在 claude mcp add-from-claude-desktop 中选中的某个服务器。该命令仍会导入其他选中的服务器，并为每个无法添加的服务器打印一行信息。在 v2.1.205 之前，第一个失败的服务器会中止整个导入，你选中的服务器都不会被添加。

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

服务器名称之后的文本是原因。最常见的原因是名称检查：Claude Desktop 允许服务器名称中包含空格和句点等字符，而 claude mcp 只允许字母、数字、短横线和下划线。其他原因包括一个未通过校验的服务器配置，以及一个被你组织的MCP 策略阻止的服务器。

该怎么做：

• 在 claude_desktop_config.json 中将该服务器重命名为只包含字母、数字、短横线和下划线的名称，然后再次运行 claude mcp add-from-claude-desktop
• 用 claude mcp add 或 claude mcp add-json，以一个有效的名称直接添加该服务器。请参阅从 Claude Desktop 导入 MCP 服务器。

插件错误

这些错误来自插件和市场配置。对于本页未涵盖信息的插件问题（例如一个无法加载的市场网址，或一个已安装却没有出现的插件），请参阅插件故障排查。

Marketplace is registered from an untrusted source

该市场注册使用的名称为 Anthropic 官方市场保留，但其注册来源不是一个 anthropics 的 GitHub 仓库。Claude Code 每次加载或刷新一个市场时都会重新检查保留名称，因此该市场以及从它安装的插件都会停止加载。在 v2.1.205 之前，这个名称只在市场被添加时检查一次，因此一个在其名称被保留之前就注册的条目会继续加载。

Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

该怎么做：

• 运行 claude plugin marketplace remove <name>，然后从官方的 github.com/anthropics 仓库重新添加该市场
• 如果你发布的第三方市场在其名称成为保留名称之前就使用了它，请重命名它，并让用户从你的来源重新添加它
• 关于保留名称列表，请参阅市场模式

配置警告

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, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

该怎么做：

• 在该目录中运行 claude，接受信任对话框。即使某个父目录已经受信任，该对话框也会出现，列出被搁置的规则，并让你可以拒绝并在没有它们的情况下继续工作。在 v2.1.200 之前，这种情况下不会出现任何对话框，因此在那里无法完成这一步。
• 在带 -p 的非交互模式下不会显示任何对话框。请用信息中打印的确切 projects 键，在 ~/.claude.json 中设置 hasTrustDialogAccepted 条目。
• 如果信息中提到的是 .claude/settings.local.json，且你是在一个 git 仓库之外或在你的主目录中启动 Claude Code 的，请更新到 v2.1.200 或更高版本。2.1.196 到 2.1.199 版本会在那些工作区中，把你自己的 .claude/settings.local.json 当作仓库提供的文件处理。请参阅项目允许规则与工作区信任。

Responses seem lower quality than usual

如果 Claude 的回答看起来不如你预期的那样出色，但没有显示任何错误，原因通常是对话状态，而不是模型本身。Claude Code 不会悄悄地更改模型版本。它可以在三种特定情况下切换到一个后备模型：

• 一个已配置的 --fallback-model，会在一次可用性错误之后接管，只针对那一轮，并在记录中显示一条提示
• Amazon Bedrock 或 Google Cloud 的 Agent Platform 的启动检查发现你的默认模型不可用
• Fable 5 上的自动模型后备会把会话切换到默认的 Opus 模型，并在记录中显示一条提示

下面的模型选择检查能捕获第二种和第三种情况；第一种会以一条记录提示出现，而不是一次 /model 更改。模型配置解释了每种后备何时适用。

先检查以下这些：

• 模型选择：运行 /model，确认你使用的是预期的模型。之前的一次 /model 选择，或一个 ANTHROPIC_MODEL 环境变量，可能让你处于一个比你预期更小的模型上。
• Effort 级别：运行 /effort 检查当前的推理级别，并为困难的调试或设计工作提高它。默认值因模型而异，因此请先检查，不要假设你已经处于最高级别。关于各模型的默认值和 ultrathink 快捷方式，请参阅调整 effort 级别。
• 上下文压力：运行 /context 查看窗口的填满程度。如果接近容量上限，在一个自然的断点处运行 /compact，或运行 /clear 重新开始。关于自动压缩如何影响较早的轮次，请参阅探索上下文窗口。
• 过时的指令：大型或过时的 CLAUDE.md 文件和 MCP 工具定义会消耗上下文，并可能左右回复的方向。/doctor 体检会标记出过大的记忆文件和未使用的扩展，/context 会显示 MCP 工具的 Token 用量。在 v2.1.205 之前，/doctor 会打开一个诊断界面，标记过大的记忆文件和子智能体定义。

当一次回复出了问题时，回退通常比用更正来回复效果更好。按两次 Esc 或运行 /rewind，退回到那个不好的轮次之前，然后用更具体的措辞重新表述提示词。在对话内进行更正，会让那次错误的尝试留在上下文中，可能会让之后的答案锚定在它上面。请参阅检查点。

如果检查完以上内容后质量仍然不理想，运行 /feedback，描述你的预期与实际得到的结果。以这种方式提交的反馈会包含对话记录，这是 Anthropic 诊断真正的回归问题最快的方式。如果 /feedback 在你的环境中不可用，请参阅报告一个错误。

如果 Sonnet 5 拒绝了一个请求，并在 Claude Code v2.1.200 或更早版本上指出怀疑存在提示注入，运行 claude update 获取 v2.1.201 的修复。

报告一个错误

对于本页未涵盖组件产生的错误，请参阅相关指南：

• MCP 服务器连接或身份验证失败：MCP
• 钩子脚本失败或阻止了某个工具：调试钩子
• 安装期间权限被拒绝或出现文件系统错误：故障排查安装与登录

如果某个错误没有在这里列出，或建议的修复方法没有帮助：

• 在 Claude Code 内运行 /feedback，把记录和一份描述发给 Anthropic。该命令还会提供打开一个预填好的 GitHub issue 的选项。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和其他第三方服务商上，/feedback 会改为保存一份本地存档，你可以将其发给你的 Anthropic 客户代表。
• 在你的 shell 中运行 claude doctor，获取安装的只读诊断信息，或在 Claude Code 内运行 /doctor 体检，查找并修复搭建问题
• 查看 status.claude.com 是否有正在发生的事件
• 在 GitHub 上搜索现有 issue