本页列出了 Claude Code 显示的运行时错误以及如何从每个错误中恢复,以及当响应似乎有问题但没有错误时要检查的内容。对于安装错误(如Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
command not found 或设置期间的 TLS 故障),请参阅故障排除安装和登录。
这些错误和恢复命令适用于 CLI、桌面应用和网络上的 Claude Code,因为这三个都包装了相同的 Claude Code CLI。对于特定于表面的问题,请参阅该表面页面上的故障排除部分。
Claude Code 调用 Claude API 获取模型响应,因此大多数运行时错误映射到底层 API 错误代码。本页介绍了每个错误在 Claude Code 中的含义以及如何恢复。有关原始 HTTP 状态代码定义,请参阅 Claude Platform 错误参考。
查找您的错误
将您在终端中看到的消息与下面的部分相匹配。| 消息 | 部分 |
|---|---|
API Error: 500 ... Internal server error | 服务器错误 |
API Error: Repeated 529 Overloaded errors | 服务器错误 |
Request timed out | 服务器错误,或如果消息提到您的互联网连接,则为网络 |
<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 | 服务器错误 |
You've hit your session limit / You've hit your weekly limit | 使用限制 |
Server is temporarily limiting requests | 使用限制 |
Request rejected (429) | 使用限制 |
Credit balance is too low | 使用限制 |
Not logged in · Please run /login | 身份验证 |
Invalid API key | 身份验证 |
This organization has been disabled | 身份验证 |
Routines are disabled by your organization's policy | 身份验证 |
OAuth token revoked / OAuth token has expired | 身份验证 |
does not meet scope requirement user:profile | 身份验证 |
Unable to connect to API | 网络 |
SSL certificate verification failed | 网络 |
403 with x-deny-reason: host_not_allowed in a cloud or routine session | 网络 |
Prompt is too long | 请求错误 |
Error during compaction: Conversation too long | 请求错误 |
Request too large | 请求错误 |
Image was too large | 请求错误 |
PDF too large / PDF is password protected | 请求错误 |
Extra inputs are not permitted | 请求错误 |
There's an issue with the selected model | 请求错误 |
Claude Opus is not available with the Claude Pro plan | 请求错误 |
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 在向您显示错误之前会重试瞬时故障。服务器错误、过载响应、请求超时、临时 429 限流和断开的连接都会以指数退避方式重试最多 10 次。重试时,微调器显示Retrying in Ns · attempt x/y 倒计时。
当您看到本页上的错误之一时,这些重试已经用尽。您可以使用两个环境变量调整行为:
| 变量 | 默认值 | 效果 |
|---|---|---|
CLAUDE_CODE_MAX_RETRIES | 10 | 重试次数。降低它以在脚本中更快地显示故障;提高它以等待更长的事件。 |
API_TIMEOUT_MS | 600000 | 每个请求的超时时间(毫秒)。为慢速网络或代理提高它。 |
服务器错误
这些错误来自 Anthropic 基础设施,而不是您的帐户或请求。API Error: 500 Internal server error
Claude Code 为任何 5xx 状态显示原始 API 响应体。下面的示例显示了 500 响应:- 检查 status.claude.com 以了解活跃事件
- 等待一分钟,然后再次发送您的消息。您的原始消息仍在对话中,因此对于长提示,您可以输入
try again而不是粘贴整个内容。 - 如果错误持续存在且没有发布的事件,请运行
/feedback,以便 Anthropic 可以使用您的请求详情进行调查。如果您的提供商上/feedback不可用,请参阅报告错误。
API Error: Repeated 529 Overloaded errors
API 在所有用户中暂时处于容量限制。Claude Code 在显示此消息之前已经重试了多次:- 检查 status.claude.com 以了解容量通知
- 几分钟后重试
- 运行
/model并切换到不同的模型以继续工作,因为容量是按模型跟踪的。当一个模型处于特别高的负载下时,Claude Code 会提示您这样做,例如Opus is experiencing high load, please use /model to switch to Sonnet。
Request timed out
API 在连接截止时间之前没有响应。- 重试请求
- 对于长时间运行的任务,将工作分解为较小的提示
- 如果是慢速网络或代理导致的,请按照自动重试中的说明提高
API_TIMEOUT_MS - 如果超时频繁且您的网络状况良好,请参阅下面的网络和连接错误
Auto mode cannot determine the safety of an action
auto mode 用来分类操作的模型无法做出决定,因此 auto mode 没有自动批准该操作。您看到的消息取决于分类器失败的原因。 在您的工作目录中的读取、搜索和编辑会跳过分类器,因此它们在所有这些情况下都继续工作。 当分类器模型过载时:- 几秒钟后重试;Claude 看到相同的消息,通常会自动重试
- 如果重试继续失败,继续进行只读任务,稍后再回到被阻止的操作
- 这是暂时的,与 auto mode 资格无关;您不需要更改设置
- 重试该操作;这通常在下一次尝试时成功
- 运行
claude --debug并重复该操作以在调试日志中查看底层分类器响应
- 在出现的提示中批准或拒绝该操作
- 运行
/compact以减少对话大小,以便后续操作再次适应分类器窗口
使用限制
这些错误意味着与您的帐户或计划相关的配额已达到。它们与影响所有人的服务器错误不同。You’ve hit your session limit
订阅计划包括滚动使用额度。当它用完时,您会看到以下消息之一:- 等待错误中显示的重置时间
- 运行
/usage以查看您的计划限制以及它们何时重置 - 运行
/extra-usage以在 Pro 和 Max 上购买额外使用,或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费的信息,请参阅付费计划的额外使用。 - 要升级您的计划以获得更高的基础限制,请参阅 claude.com/pricing
rate_limits 字段添加到自定义状态行,或在桌面应用中单击模型选择器旁边的使用环。
Server is temporarily limiting requests
API 应用了与您的计划配额无关的短期限流。- 等待片刻后重试
- 如果持续存在,请检查 status.claude.com
Request rejected (429)
您已达到为您的 API 密钥、Amazon Bedrock 项目或 Google Vertex AI 项目配置的速率限制。- 运行
/status并确认活跃凭证是您期望的凭证。环境中的流浪ANTHROPIC_API_KEY可能会通过低层密钥而不是您的订阅路由请求。 - 检查您的提供商控制台以了解活跃限制,如果需要,请请求更高的层级
- 对于 Anthropic API 密钥,请参阅速率限制参考以了解层级如何工作以及如何设置每个工作区的上限
- 降低并发:降低
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY,避免运行许多并行子代理,或使用/model切换到较小的模型以进行高容量脚本运行
Credit balance is too low
您的 Console 组织已用完预付信用。- 在 platform.claude.com/settings/billing 添加信用,并考虑在那里启用自动重新加载,以便在余额达到零之前重新填充
- 如果您有 Pro、Max、Team 或 Enterprise 计划,请使用
/login切换到订阅身份验证 - 在 Console 中设置每个工作区的支出上限,以防止单个项目耗尽组织余额。请参阅有效管理成本。
身份验证错误
这些错误意味着 Claude Code 无法向 API 证明您的身份。随时运行/status 以查看当前活跃的凭证。
Not logged in
此会话没有有效的凭证可用。- 运行
/login以使用您的 Claude 订阅或 Console 帐户进行身份验证 - 如果您期望环境变量对您进行身份验证,请确认
ANTHROPIC_API_KEY已在您启动claude的 shell 中设置和导出 - 对于 CI 或无法进行交互式登录的自动化,配置一个
apiKeyHelper脚本,在启动时获取密钥 - 请参阅身份验证优先级以了解当存在多个凭证时哪个凭证获胜
Invalid API key
ANTHROPIC_API_KEY 环境变量或 apiKeyHelper 脚本返回了 API 拒绝的密钥。
- 检查拼写错误,并确认密钥未在 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 正在覆盖您的订阅登录。
/login,因此在您的 shell 配置文件中导出或从 .env 文件加载的密钥即使您有有效的 Pro 或 Max 订阅也会被使用。在非交互模式 (-p) 中,当存在密钥时总是使用该密钥。
要做什么:
- 在当前 shell 中取消设置
ANTHROPIC_API_KEY并从您的 shell 配置文件中删除它,然后重新启动claude - 之后运行
/status以确认活跃凭证是您的订阅 - 如果未设置环境变量且错误仍然存在,则禁用的组织是与您的
/login相关联的组织。联系支持或使用不同的帐户登录。
Routines are disabled by your organization’s policy
您的团队或企业管理员已在组织级别关闭了例程。当您尝试创建或运行例程时会出现该错误,包括从/schedule 和 claude.ai/code 上的 Routines UI。
- 要求您的管理员在 claude.ai/admin-settings/claude-code 启用例程切换
- 对于不需要组织级别例程的一次性计划工作,请参阅计划任务
OAuth token revoked or expired
您保存的登录不再有效。撤销的令牌意味着您在任何地方都签出或管理员删除了访问权限;过期的令牌意味着自动刷新在会话中途失败。- 运行
/login以再次登录 - 如果在重新身份验证后错误在同一会话中返回,请先运行
/logout以完全清除存储的令牌,然后运行/login - 对于跨启动的重复登录提示,请参阅故障排除中的系统时钟和 macOS Keychain 检查
- 对于其他故障,包括
403 Forbidden和 OAuth 浏览器问题,请参阅登录和身份验证
OAuth scope requirement
存储的令牌早于较新功能所需的权限范围。您最常从/usage 和状态行使用指示器看到这一点:
- 运行
/login以使用当前范围铸造新令牌。您不需要先登出。
网络和连接错误
这些错误意味着来自 Claude Code 的网络请求无法到达其目的地。它们通常源于您的本地网络、代理或防火墙,或云环境的网络策略。Unable to connect to API
到 API 的 TCP 连接失败或从未完成。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设置为其地址。有关设置,请参阅 LLM 网关配置。 - 确保您的防火墙允许网络访问要求中列出的主机
- 间歇性故障会自动重试;持续故障指向本地网络问题
curl 成功但 Claude Code 仍然失败,原因通常是运行时和网络之间的某些东西,而不是网络本身:
- 在 Linux 和 WSL 上,检查
/etc/resolv.conf是否有无法到达的名称服务器。特别是 WSL 可以从主机继承损坏的解析器。 - 在 macOS 上,已断开连接或卸载的 VPN 客户端可能会留下隧道接口或路由规则。检查
ifconfig以查找过时的utun接口,并在系统设置中删除 VPN 的网络扩展。 - Docker Desktop 和类似的容器运行时可以拦截出站流量。退出它们并重试以排除这一点。
SSL certificate errors
您网络上的代理或安全设备正在使用其自己的证书拦截 TLS 流量,而 Claude Code 不信任它。- 导出您组织的 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 请求被环境的网络策略阻止。- 打开例程进行编辑,或启动云会话。选择显示您的环境名称(如 Default)的云图标以打开选择器。将鼠标悬停在您的环境上并单击设置图标。
- 在 Update cloud environment 对话框中,将 Network access 从 Trusted 更改为 Custom,然后将被阻止的域添加到 Allowed domains。每行输入一个域。选中 Also include default list of common package managers 以在自定义域旁边保留默认允许列表。如果您想要不受限制的访问,请改为选择 Full。
- 单击 Save changes。下一次运行使用更新的允许列表。
请求错误
这些错误意味着 API 收到了您的请求但拒绝了其内容。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 本身失败,因为没有足够的可用上下文来保存它生成的摘要。
Prompt is too long 后运行 /compact 时,可能会发生这种情况。
要做什么:
- 按 Esc 两次打开消息列表并回退几轮。这会从上下文中删除最近的消息。然后再次运行
/compact。 - 如果回退没有释放足够的空间,请运行
/clear以启动新的会话。您之前的对话已保存,可以使用/resume重新打开。
Request too large
原始请求体在标记化之前超过了 API 的字节限制,通常是因为粘贴的大文件或附件。- 按 Esc 两次并回退到添加超大内容的轮次之前
- 按路径引用大文件而不是粘贴其内容,以便 Claude 可以分块读取它们
- 对于图像,请参阅下面的图像太大
Image was too large
粘贴或附加的图像超过了 API 的大小或尺寸限制。- 按 Esc 两次并回退到添加图像的轮次之前
- 在粘贴之前调整图像大小。API 接受单个图像最长边最多 8000 像素的图像,或当许多图像在上下文中时为 2000 像素。
- 拍摄相关区域的更紧密屏幕截图,而不是整个屏幕
PDF errors
您附加的 PDF 无法处理。- 对于超大 PDF,要求 Claude 使用 Read 工具读取页面范围而不是附加整个文件,或使用
pdftotext等工具提取文本并按路径引用输出文件 - 对于受保护或无效的 PDF,删除密码或从其源应用程序重新导出文件,然后重试
Extra inputs are not permitted
Claude Code 和 API 之间的代理或 LLM 网关删除了anthropic-beta 请求标头,因此 API 拒绝了依赖它的字段。
context_management、effort 和工具 input_examples,以及启用它们的 anthropic-beta 标头。当网关转发正文但删除标头时,API 看到它不识别的字段。
要做什么:
- 配置您的网关以转发
anthropic-beta标头。请参阅 LLM 网关配置。 - 作为后备,在启动之前设置
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。这会禁用需要 beta 标头的功能,以便请求通过无法转发它的网关成功。
There’s an issue with the selected model
配置的模型名称未被识别或您的帐户缺少对它的访问权限。- 运行
/model以从您的帐户可用的模型中选择 - 使用别名(如
sonnet或opus)而不是完整的版本化 ID。别名跟踪最新版本,因此它们不会过时。请参阅模型配置。 - 如果错误的模型一直出现,则某处设置了过时的 ID。按优先级顺序检查:
--model标志、ANTHROPIC_MODEL环境变量,然后是.claude/settings.local.json中的model字段、您项目的.claude/settings.json和~/.claude/settings.json。删除过时的值,Claude Code 将回退到您的帐户默认值。 - 对于 Vertex AI 部署,请参阅 Vertex AI 故障排除。
Claude Opus is not available with the Claude Pro plan
您的活跃订阅计划不包括您选择的模型。- 运行
/model并选择您的计划包括的模型 - 如果您最近升级了计划但仍然看到这个,请运行
/logout然后/login。存储的令牌反映了您登录时的计划,因此在现有会话中升级网络不会生效,直到您重新身份验证。 - 有关每个计划包括哪些模型,请参阅 claude.com/pricing
thinking.type.enabled is not supported for this model
您的 Claude Code 版本早于 Opus 4.7 的最低版本。CLI 发送了模型不再接受的思考配置。- 运行
claude update以升级到 v2.1.111 或更高版本,然后重新启动 Claude Code - 如果您无法升级,请运行
/model并选择 Opus 4.6 或 Sonnet - 如果您在 Agent SDK 中遇到这个,请参阅 SDK 故障排除
Thinking budget exceeds output limit
配置的扩展思考预算超过了最大响应长度,因此没有空间留给实际答案。MAX_THINKING_TOKENS 设置高于提供商的输出限制时,或当计划模式提高思考预算时,您通常会在 Amazon Bedrock 或 Google Vertex AI 上看到此错误。
要做什么:
- 降低
MAX_THINKING_TOKENS,或将CLAUDE_CODE_MAX_OUTPUT_TOKENS提高到思考预算之上 - 有关预算如何与输出长度交互的信息,请参阅扩展思考
Tool use or thinking block mismatch
对话历史以不一致的状态到达 API,通常是在工具调用被中断或轮次在流中途被编辑后。tool_use、tool_result 和 thinking 块的序列不再与 API 期望的相匹配。
要做什么:
- 运行
/rewind,或按 Esc 两次,回退到损坏轮次之前的检查点并从那里继续。有关如何创建和恢复检查点的信息,请参阅检查点。
响应质量似乎低于平常
如果 Claude 的答案似乎不如您期望的那样有能力,但没有显示错误,原因通常是对话状态而不是模型本身。Claude Code 不会默默更改模型版本。它可以在特定情况下切换到后备模型,例如达到 Opus 配额或 Bedrock 或 Vertex AI 区域缺少您的模型;下面的模型选择检查会捕获两者,模型配置解释了何时应用后备。 首先检查这些:- 模型选择:运行
/model以确认您在期望的模型上。之前的/model选择或ANTHROPIC_MODEL环境变量可能会让您使用比您打算的更小的模型。 - 努力级别:运行
/effort以检查当前推理级别并为困难的调试或设计工作提高它。默认值因模型而异,因此在假设您低于最大值之前检查。有关每个模型的默认值和ultrathink快捷方式,请参阅调整努力级别。 - 上下文压力:运行
/context以查看窗口有多满。如果接近容量,请在自然断点处运行/compact或运行/clear以重新开始。有关自动压缩如何影响早期轮次的信息,请参阅探索上下文窗口。 - 过时的说明:大型或过时的
CLAUDE.md文件和 MCP 工具定义消耗上下文并可能引导响应。/doctor标记超大内存文件和子代理定义;/context显示 MCP 工具令牌使用。
/rewind 以回退到坏轮次之前,然后用更多细节重新表述提示。在线程中更正会将错误的尝试保留在上下文中,这可能会将后来的答案锚定到它。请参阅检查点。
如果在检查上述内容后质量仍然似乎有问题,请运行 /feedback 并描述您期望的内容与您得到的内容。以这种方式提交的反馈包括对话记录,这是 Anthropic 诊断真实回归的最快方式。如果您的提供商上 /feedback 不可用,请参阅报告错误。
报告错误
本页涵盖来自 Claude API 的错误。对于来自其他 Claude Code 组件的错误,请参阅相关指南: 如果此处未列出错误或建议的修复无法帮助:- 在 Claude Code 中运行
/feedback以将记录和描述发送给 Anthropic。该命令还提供打开预填充的 GitHub 问题。Bedrock、Vertex AI 和 Foundry 部署上不提供反馈。 - 运行
/doctor以检查本地配置问题 - 检查 status.claude.com 以了解活跃事件
- 在 GitHub 上搜索现有问题