SpyBara
Go Premium

errors.md 2026-07-09 23:58 UTC to 2026-07-10 17:00 UTC

488 added, 272 removed.

2026
Sat 11 19:03 Fri 10 17:00 Thu 9 23:58 Wed 8 16:02 Tue 7 16:02 Mon 6 23:57 Sat 4 03:01 Fri 3 23:00 Thu 2 23:59 Wed 1 21:01

错误参考

查找 Claude Code 运行时错误消息，了解每个错误的含义以及如何修复。

本页列出了 Claude Code 显示的运行时错误以及如何从每个错误中恢复，以及当响应似乎有问题但没有错误时要检查的内容。对于安装错误（如 command not found 或设置期间的 TLS 故障），请参阅故障排除安装和登录。

这些错误和恢复命令适用于 CLI、桌面应用和网络上的 Claude Code，因为这三个都包装了相同的 Claude Code CLI。对于特定于表面的问题，请参阅该表面页面上的故障排除部分。

查找您的错误

将您在终端中看到的消息与下面的部分相匹配。

消息 部分
API Error: 500 Internal server error 服务器错误
API Error: Repeated 529 Overloaded errors 服务器错误
Request timed out 服务器错误，或网络（如果消息提到您的互联网连接）
Server error mid-response. The response above may be incomplete. 服务器错误
Connection closed mid-response / Response stalled mid-stream 服务器错误
<model> is temporarily unavailable, so auto mode cannot determine the safety of... 服务器错误
Auto mode could not evaluate this action and is blocking it for safety 服务器错误
Auto mode classifier transcript exceeded context window 服务器错误
Agent terminated early due to an API error 服务器错误
You've hit your session limit / You've hit your weekly limit 使用限制
Usage credits required for 1M context 使用限制
Server is temporarily limiting requests 使用限制
Request rejected (429) 使用限制
Credit balance is too low 使用限制
Not logged in · Please run /login 身份验证
Could not resolve authentication method 身份验证
Invalid API key 身份验证
This organization has been disabled 身份验证
Your organization has disabled API key authentication 身份验证
Your organization has disabled Claude subscription access 身份验证
Routines are disabled by your organization's policy 身份验证
Remote Control is only available when using Claude via api.anthropic.com 身份验证
OAuth token revoked / OAuth token has expired 身份验证
does not meet scope requirement user:profile 身份验证
AWS credentials expired or invalid 身份验证
AWS authentication failed 身份验证
Unable to connect to API 网络
Waiting for API response · will retry in 自动重试，或网络（如果问题持续）
SSL certificate verification failed 网络
SSL certificate error (...) during login or startup 网络
403 with x-deny-reason: host_not_allowed in a cloud or routine session 网络
Couldn't reconnect to your Remote Control session 网络
Prompt is too long 请求错误
Error during compaction: Conversation too long 请求错误
Request too large 请求错误
Image was too large 请求错误
Unable to resize image 请求错误
PDF too large / PDF is password protected 请求错误
Extra inputs are not permitted 请求错误
There's an issue with the selected model 请求错误
Model ... is not a recognized model id 请求错误
Claude Opus is not available with the Claude Pro plan 请求错误
Model ... is restricted by your organization's settings 请求错误
thinking.type.enabled is not supported for this model 请求错误
max_tokens must be greater than thinking.budget_tokens 请求错误
API Error: 400 due to tool use concurrency issues 请求错误
Claude Code is unable to respond to this request, which appears to violate our Usage Policy 请求错误
<model> has safety measures that flagged this message for a cybersecurity topic 请求错误
Installation was killed before it could finish (exit code 137) 安装错误
The connection dropped while downloading the update 安装错误
Download timed out: exceeded the total deadline 安装错误
--bg and --print conflict 命令行错误
Error: --json-schema is not a valid JSON Schema 命令行错误
Could not import <server>: <reason> 命令行错误
Marketplace "<name>" is registered from an untrusted source 插件错误
Ignoring N permissions.allow entries from ... this workspace has not been trusted 配置警告
响应质量似乎低于平常 响应质量

自动重试

Claude Code 在向您显示错误之前会重试瞬时故障。服务器错误、过载响应、请求超时、临时 429 限流和断开的连接都会以指数退避方式重试最多 10 次。{/* min-version: 2.1.198 /}从 v2.1.198 开始，这涵盖了在任何可见输出流出之前在响应中途断开的连接：Claude Code 使用相同的退避重新发出请求，轮次继续而不是停止并显示连接错误。{/ min-version: 2.1.199 */}从 v2.1.199 开始，不携带您计划配额标头的临时 429 限流在您使用 claude.ai 订阅登录时也会重试；早期版本仅对 API 密钥和企业登录重试它们。

两个故障类别不会重试，因为重试无法成功：

  • {/* min-version: 2.1.199 */}从 v2.1.199 开始，TLS 证书验证失败（例如 TLS 检查代理、缺少 NODE_EXTRA_CA_CERTS 包或过期证书）在第一次尝试时失败，因此修复立即出现，而不是在完整重试预算之后。请参阅 SSL 证书错误。瞬时 TLS 条件（例如握手超时）仍然会重试。
  • {/* min-version: 2.1.199 */}从 v2.1.199 开始，在 Claude 已经流出可见输出后到达的服务器错误会保留部分响应并附加不完整响应通知，而不是重试，因为重新运行请求可能会执行相同的工具两次。早期版本丢弃了部分输出并将轮次报告为错误。

重试时，微调器在错误标签后显示 Retrying in Ns · attempt x/y 倒计时。标签命名了第一次尝试中您可以立即采取行动的特定原因：网络已关闭、TLS 握手失败或您达到了速率限制。对于其他错误，它最初读作 API error。{/* min-version: 2.1.198 */}从 v2.1.198 开始，它切换到第三次尝试中的特定原因，或当 CLAUDE_CODE_MAX_RETRIES 允许少于三次时在最后一次尝试；早期版本仅在最后一次尝试时切换。

{/* min-version: 2.1.198 */}从 v2.1.198 开始，重试期间会抑制通常的微调器提示。一旦错误原因被揭示，如果故障是 529 过载，倒计时下方的行也会命名检查服务状态的位置：Anthropic API 上的 status.claude.com，或其他配置上的提供商或网关主机。

{/* min-version: 2.1.185 */}如果在请求仍然待处理时，响应流上 20 秒内没有数据到达，微调器会显示 Waiting for API response · will retry in … · check your network，然后再进行任何重试。请求尚未失败：倒计时运行到 Claude Code 中止停滞连接并重试的点，因此一旦数据恢复或重试成功，横幅就会自动清除。从 v2.1.185 开始，阈值为 20 秒；早期版本在 10 秒后显示横幅，措辞不同。如果它在每次尝试时都重新出现，请将其视为网络问题。

当您看到本页上的错误之一时，这些重试已经用尽，除非它属于不会重试的类别，例如证书验证失败。您可以使用这些环境变量调整行为：

变量 默认值 效果
CLAUDE_CODE_MAX_RETRIES 10 重试次数。{/* min-version: 2.1.186 /}从 v2.1.186 开始上限为 15；{/ min-version: 2.1.199 */}从 v2.1.199 开始 CLAUDE_CODE_RETRY_WATCHDOG 提高默认值并移除上限。降低它以在脚本中更快地显示故障。
CLAUDE_CODE_RETRY_WATCHDOG 未设置 在 CI 作业等无人值守会话中设置为 1，以无限期重试 429 和 529 容量错误，而不是在 CLAUDE_CODE_MAX_RETRIES 次尝试后失败。{/* min-version: 2.1.199 */}从 v2.1.199 开始，它也提高了其他瞬时错误（例如服务器错误、超时和断开的连接）的默认重试计数至 300，大约三小时的退避，如果您显式设置该变量，则移除 CLAUDE_CODE_MAX_RETRIES 的 15 上限。
API_TIMEOUT_MS 600000 每个请求的超时时间（毫秒）。为慢速网络或代理提高它。

服务器错误

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

API 错误：500 内部服务器错误

Claude Code 显示任何 5xx 响应的状态代码和 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 错误：重复的 529 过载错误

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。

请求超时

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

Request timed out

这可能发生在高负载期间或模型生成非常大的响应时。默认请求超时为 10 分钟。

应该做什么：

  • 重试请求
  • 对于长时间运行的任务，将工作分解为较小的提示
  • 如果是由于网络缓慢或代理引起的，请按照自动重试中的说明提高 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.
  • {/* min-version: 2.1.199 */}}Server error mid-response：流中的过载或 5xx 服务器错误。此变体需要 Claude Code v2.1.199 或更高版本；在此之前，该情况会丢弃部分输出并将整个轮次报告为错误。
  • Connection closed mid-response：连接断开。
  • Response stalled mid-stream：流停止发送数据。

应该做什么：

  • 阅读流式传输的响应。没有任何内容丢失，但最后的句子或工具调用可能缺失。
  • 回复 continue 让 Claude 从停止的地方继续
  • 如果在任何可见输出之前出现相同的错误，Claude Code 会重试请求而不是完成它。请参阅自动重试。

自动模式无法确定操作的安全性

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

在您的工作目录内的读取、搜索和编辑会跳过分类器，因此在所有这些情况下都能继续工作。

当分类器模型过载时：

<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 以减少对话大小，以便后续操作再次适应分类器窗口

代理因 API 错误而提前终止

{/* min-version: 2.1.199 */}子代理的 API 请求终止失败，例如因为达到了使用限制或服务器错误的重试用尽，所以子代理在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是子代理的结果一样。

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

应该做什么：

  • 将冒号后的错误详情与此页面上的其自己的部分相匹配，例如使用限制或服务器错误，并按照该部分的步骤操作
  • 一旦底层错误清除，请要求 Claude 重试任务或恢复子代理

当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 会收到该部分输出标记为不完整，而不是此错误。{/* min-version: 2.1.200 */}仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅子代理中的 API 错误。

使用限制

这些错误表示与您的账户或计划相关的配额已达到。它们不同于服务器错误，后者会影响所有人。

您已达到会话限制

订阅计划包括滚动使用额度。当额度用尽时，您会看到以下消息之一：

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 字段添加到自定义状态行，或在桌面应用中单击模型选择器旁边的使用量环。

1M 上下文需要使用额度

所选模型使用 1M 令牌扩展上下文窗口，而您的计划仅通过使用额度包含它。

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

这是一项权利检查，而不是配额耗尽。即使您的会话和每周额度仍有容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度，请参阅扩展上下文。

{/* min-version: 2.1.172 */}当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并在之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本上，错误会在每个后续请求（包括 /compact）上重复出现；在这些版本上运行 /clear 以恢复。以下步骤适用于您明确选择 [1m] 模型的情况。

应该怎么做：

  • 运行 /model 并选择不带 [1m] 后缀的变体以回退到标准上下文窗口
  • 运行 /usage-credits 在 Pro 和 Max 上为 1M 变体启用按量计费，或在 Team 和 Enterprise 上向您的管理员请求
  • 如果 /model 后错误仍然存在，1M 模型 ID 可能在其他地方设置。有关要按优先级顺序检查的配置位置，请参阅所选模型存在问题。
  • 要从模型选择器中完全删除 1M 变体，请设置 CLAUDE_CODE_DISABLE_1M_CONTEXT=1

服务器暂时限制请求

API 应用了与您的计划配额无关的短期限流。

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

Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些与您的计划限制。{/* min-version: 2.1.199 */}从 v2.1.199 开始，无论您如何进行身份验证，这都会自动重试并进行退避，然后才会显示。在早期版本上，使用 claude.ai 订阅登录的会话在第一次出现时失败；只有 API 密钥和 Enterprise 登录会重试。

应该怎么做：

请求被拒绝 (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 切换到较小的模型以进行大容量脚本运行

信用余额过低

您的 Console 组织已用尽预付信用。

Credit balance is too low

应该怎么做：

  • 在 platform.claude.com/settings/billing 添加信用，并考虑在那里启用自动重新加载，以便在余额达到零之前进行补充
  • 如果您有 Pro、Max、Team 或 Enterprise 计划，请使用 /login 切换到订阅身份验证
  • 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅有效管理成本。

身份验证错误

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

未登录

此会话没有可用的有效凭证。

Not logged in · Please run /login

应该做什么：

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

如果您被反复提示登录，请参阅 未登录或令牌过期 了解系统时钟和 macOS Keychain 修复。

无法解析身份验证方法

会话到达 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

{/* min-version: 2.1.174 */}在 v2.1.174 之前，分配给空闲预初始化工作进程的后台或云会话即使配置了有效凭证也可能以这种方式失败。升级以恢复。在当前版本中，该错误意味着工作进程没有可用的凭证。

应该做什么：

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

无效的 API 密钥

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 实际使用的凭证源

此组织已被禁用

来自已禁用 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 关联的组织。联系支持或使用不同的账户登录。

您的组织已禁用 API 密钥身份验证

此消息需要 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 中重新启用它

您的组织已禁用 Claude 订阅访问

您的 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 支持

例程被您的组织的策略禁用

您的 Team 或 Enterprise 组织中的所有者已在组织级别关闭例程。当您尝试创建或运行例程时会出现该错误，包括从 /schedule 和 claude.ai/code 上的 Routines UI。

Routines are disabled by your organization's policy.

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

应该做什么：

Remote Control 需要 Anthropic API

会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端供 Remote Control 配对。

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

这出现在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}从 v2.1.196 开始，当 ANTHROPIC_BASE_URL 指向 api.anthropic.com 以外的主机时，例如 LLM 网关 或代理，即使您使用 claude.ai 登录，它也会出现。

应该做什么：

  • 取消设置 ANTHROPIC_BASE_URL 并重启会话，或从直接与 Anthropic API 通信的会话启动 Remote Control
  • 对于此错误和其他 Remote Control 启动消息，请参阅 Remote Control 故障排除

OAuth 令牌被撤销或过期

您保存的登录不再有效。撤销的令牌意味着您在任何地方都已登出或管理员删除了访问权限；过期的令牌意味着自动刷新在会话中途失败。

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

应该做什么：

  • 运行 /login 重新登录
  • 如果在同一会话中重新身份验证后错误返回，请先运行 /logout 完全清除存储的令牌，然后运行 /login
  • 对于跨启动的重复登录提示，请参阅 故障排除 中的系统时钟和 macOS Keychain 检查
  • 对于其他故障，包括 403 Forbidden 和 OAuth 浏览器问题，请参阅 登录和身份验证

OAuth 范围要求

存储的令牌早于较新功能需要的权限范围。您最常从 /usage 和状态行使用情况指示器看到这一点：

OAuth token does not meet scope requirement: user:profile

应该做什么：

  • 运行 /login 获取具有当前范围的新令牌。您不需要先登出。

AWS 凭证已过期或无效

{/* min-version: 2.1.198 */}此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 awsAuthRefresh 时才会出现。您的 AWS 会话令牌已过期或被拒绝，Claude Code 已运行的自动刷新未产生 API 接受的凭证。它出现在来自 Claude Platform on AWS 或 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 和配置文件中使用 aws sts get-caller-identity 确认身份在 Claude Code 外部有效

AWS 身份验证失败

{/* min-version: 2.1.198 */}此消息需要 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 配置 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的账户和区域启用
  • 运行 aws sts get-caller-identity 确认您的请求使用哪个身份；过时的 AWS_PROFILE 或默认配置文件是权限不匹配的常见原因

网络和连接错误

这些错误表示来自 Claude Code 的网络请求未能到达其目的地。它们通常源于您的本地网络、代理或防火墙，或云环境的网络策略。

无法连接到 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

常见原因包括没有互联网访问、阻止 api.anthropic.com 的 VPN，或未配置的必需企业代理。

应该做什么：

  • 通过在同一 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 证书错误

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

{/* min-version: 2.1.199 */}从 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，这会完全禁用证书验证

云会话中不允许的主机

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

HTTP 403
x-deny-reason: host_not_allowed

您也可能看到与目的地真实证书不匹配的 TLS 证书。云环境通过代理路由出站流量以强制执行网络策略，因此证书不匹配意味着代理终止了连接，而不是目的地。

这不是客户端网络问题。云会话和例程在沙箱环境内运行，其出站流量被过滤到环境的允许列表。默认环境使用受信任访问，允许默认允许列表中的包注册表、云提供商 API、容器注册表和常见开发域，但阻止其他所有内容。

应该做什么：

  • 打开例程进行编辑，或启动云会话。选择显示您的环境名称（例如默认）的云图标以打开选择器。将鼠标悬停在您的环境上，然后单击设置图标。
  • 在更新云环境对话框中，将网络访问从受信任更改为自定义，然后将被阻止的域添加到允许的域。每行输入一个域。选中也包括常见包管理器的默认列表以在自定义域旁边保留默认允许列表。如果您想要不受限制的访问，请改为选择完全。
  • 单击保存更改。下一次运行使用更新的允许列表。

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

无法重新连接到您的 Remote Control 会话 

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

使用 claude --resume 或 claude --continue 恢复会重新连接到该对话中记录的 Remote Control 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。您的本地会话继续运行而不使用 Remote Control。

应该做什么：

  • 运行 /remote-control 以重试连接
  • 启动 Claude Code 而不使用 --resume 以创建新的 Remote Control 会话
  • 有关其他 Remote Control 启动消息，请参阅排查 Remote Control 故障

当服务器确认前一个会话不再存在时，您不会看到此消息；Claude Code 在这种情况下会创建一个新的会话。{/* min-version: 2.1.200 */}在 v2.1.200 之前，任何重新连接失败都会创建一个新的 Remote Control 会话，这在 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

{/* min-version: 2.1.142 */}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，以及启用它们的 anthropic-beta 头。当网关转发正文但删除头时，API 会看到它不识别的字段。

应该做什么：

  • 配置您的网关以转发 anthropic-beta 头。请参阅功能传递了解网关必须转发的内容。
  • 作为备选方案，在启动前设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。这会禁用需要测试版头的功能，以便请求通过无法转发它的网关成功。

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)：使用有效的别名或 ID 传递 --model，或设置 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 中的 model 字段、您项目的 .claude/settings.json 和 ~/.claude/settings.json。删除过时的值，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 的应用程序（如 Desktop app）设置模型的情况。

应该做什么：

  • 运行不带参数的 /model 来打开选择器并从您账户可用的模型中选择，然后传递那里显示的别名或 ID
  • 如果您使用了较新 Claude Code 版本支持的别名，运行 claude update。以 claude- 开头的完整 ID 即使模型比您的 Claude Code 版本更新，也会通过此检查，因此不需要升级。
  • v2.1.200 之前保存的模型不会被此检查修复。如果过时的值一直出现，请从所选模型有问题下列出的位置中删除它。
  • 检查仅在 Anthropic API 上运行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、Claude Platform on AWS 和 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 和 Claude Platform on AWS 上，受限的族别名解析为您的组织和 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
  • {/* min-version: agent-sdk@0.3.197 */}如果您在 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 上自动调整这些值。您通常在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此错误，当 MAX_THINKING_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 期望的相匹配。

应该做什么：

  • {/* max-version: 2.1.155 */}如果您使用的是 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 中仍然可用。
  • 在非交互模式(-p) 中，其中 rewind 不可用，在没有 --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；此版本仅更改了消息的措辞和它链接到的页面。

您看到的内容取决于您的提供商和模式：

{/* max-version: 2.1.202 */}在 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 Code 时出现，来自安装脚本、claude install 或 claude update。对于设置期间的 command not found、PATH、权限和 TLS 问题，请参阅排查安装和登录问题。

安装在完成前被中止

安装脚本会报告 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 行退出。

应该做什么：

下载更新时连接断开

在 claude install、claude update 或自动更新程序获取 Claude Code 二进制文件时，与下载服务器的连接关闭，重试未能恢复。当连接断开、传输停滞或下载的文件未通过校验和时，Claude Code 会重试下载，总共最多尝试三次。已完成的 HTTP 错误（例如 404）不会重试，因为服务器已经响应。{/* min-version: 2.1.202 */}在 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 请求之前会打印这些错误。

\--bg 和 --print 之间的冲突

此消息需要 Claude Code v2.1.198 或更高版本。您在同一个 claude 调用中将 --bg 与 -p 或 --print 组合在一起。--bg 启动一个后台会话，您稍后可以使用 claude agents 附加到该会话，而 --print 以非交互方式运行，永远不会启动 claude agents 附加到的交互式会话。在 v2.1.198 之前，此组合会静默创建一个永远无法附加的后台作业。

--bg 和 --print 冲突：--print 永远不会启动 `claude agents` 附加到的交互式会话，因此该作业将无法附加。提示是位置参数 — 删除 --print：`claude --bg '<task>'`。

应该怎么做：

  • 删除 -p 或 --print。--bg 将提示作为其位置参数，因此 claude --bg "<task>" 是完整命令。请参阅从您的 shell 分派新代理。
  • 要以非交互方式运行提示并打印结果而不是创建后台会话，请删除 --bg 并运行 claude -p "<task>"

\--json-schema 值不是有效的 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 在架构编译之前运行两项检查：它拒绝不可解析的 JSON 值，并显示 Error: --json-schema is not valid JSON，以及不是对象的有效 JSON，并显示 Error: --json-schema must be a JSON object。

应该怎么做：

  • 修复诊断命名的架构部分，然后重新运行命令
  • 如果诊断是 schema too large，请减少架构的嵌套和 $ref 重用
  • 请参阅获取结构化输出以获取有效的架构和命令

无法从 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 服务器。

Plugin 错误

这些错误来自 plugin 和 marketplace 配置。对于不会产生此页面上的消息之一的 plugin 问题，例如无法加载的 marketplace URL 或已安装但不显示的 plugin，请参阅 Plugin troubleshooting。

Marketplace 从不受信任的源注册

marketplace 以 为官方 Anthropic marketplace 保留的名称 注册，但其注册源不是 anthropics GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 和从中安装的 plugin 停止加载。在 v2.1.205 之前，仅在添加 marketplace 时检查名称，因此在其名称被保留之前注册的条目继续加载。

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 存储库重新添加 marketplace
  • 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的源重新添加它
  • 查看 Marketplace schema 下的保留名称列表

配置警告

Claude Code 在启动时将这些消息写入 stderr，而不是在对话中显示错误。它们报告 Claude Code 读取但未应用的配置。

工作区尚未被信任

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 并接受信任对话框。{/* min-version: 2.1.200 */}即使父目录已被信任，对话框也会出现，列出被保留的规则，并让您可以拒绝并继续工作而不应用这些规则。在 v2.1.200 之前，在这种情况下不会出现对话框，因此无法在那里完成此步骤。
  • 在非交互模式中使用 -p 不会显示对话框。使用消息打印的确切 projects 键在 ~/.claude.json 中设置 hasTrustDialogAccepted 条目。
  • {/* min-version: 2.1.200 */}如果消息命名 .claude/settings.local.json 并且您在 git 存储库外部或在主目录中启动了 Claude Code，请更新到 v2.1.200 或更高版本。版本 2.1.196 至 2.1.199 在这些工作区中将您自己的 .claude/settings.local.json 视为存储库提供的。请参阅项目允许规则和工作区信任。

响应质量似乎低于预期

如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在三种特定情况下切换到备用模型：

  • 配置的 --fallback-model 在可用性错误后接管该轮次，并在记录中显示通知
  • Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用
  • 自动模型备用在 Fable 5 上将会话移至默认 Opus 模型，并在记录中显示通知

下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 /model 更改。模型配置解释了每种备用何时适用。

首先检查这些：

  • 模型选择：运行 /model 以确认你在预期的模型上。之前的 /model 选择或 ANTHROPIC_MODEL 环境变量可能使你在比预期更小的模型上。
  • 努力级别：运行 /effort 以检查当前推理级别，并为困难的调试或设计工作提高它。默认值因模型而异，所以在假设你低于最大值之前请检查。有关每个模型的默认值和 ultrathink 快捷方式，请参阅调整努力级别。
  • 上下文压力：运行 /context 以查看窗口有多满。如果接近容量，在自然断点处运行 /compact 或运行 /clear 以重新开始。有关自动压缩如何影响早期轮次的信息，请参阅探索上下文窗口。
  • 过时的指令：大型或过时的 CLAUDE.md 文件和 MCP 工具定义会消耗上下文并可能引导响应。{/* min-version: 2.1.205 */}/doctor 检查会标记超大内存文件和未使用的扩展，/context 显示 MCP 工具令牌使用情况。在 v2.1.205 之前，/doctor 打开一个诊断屏幕，标记超大内存文件和子代理定义。

当响应出错时，回退通常比用更正进行回复效果更好。按两次 Esc 或运行 /rewind 以回到错误轮次之前，然后用更具体的内容重新表述提示。在线程中更正会将错误的尝试保留在上下文中，这可能会将后来的答案锚定到它。请参阅检查点。

如果在检查上述内容后质量仍然似乎不对，请运行 /feedback 并描述你期望的内容与你得到的内容。以这种方式提交的反馈包括对话记录，这是 Anthropic 诊断真实回归的最快方式。如果 /feedback 在你的环境中不可用，请参阅报告错误。

{/* min-version: 2.1.201 */}如果 Sonnet 5 拒绝请求并在 Claude Code v2.1.200 或更早版本上引用可疑的提示注入，请运行 claude update 以获取 v2.1.201 修复。

报告错误

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

如果此处未列出错误或建议的修复方法无法帮助：

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