网络、请求与安装错误

错误措辞、版本号和各模型的最低版本随发布变化，以官方为准。

网络与连接错误

多数表示 Claude Code 的网络请求没能到达目的地，或 Claude Code 与 API 之间的某处在响应回来的路上改动了它；也有本地原因（如归档写入失败）。它们通常源于你的本地网络、代理、防火墙，或云环境的网络策略。

Unable to connect to API

到 API 的 TCP 连接失败或始终没有完成；对常见的连接错误码，消息会点名失败的种类并把错误码放在括号里，不认识的错误码则显示为 Unable to connect to API 后接该码。怎么办：在同一 shell 里 curl -I https://api.anthropic.com 确认能到达 API 主机（Windows PowerShell 用 curl.exe -I ...，避免内置的 Invoke-WebRequest 别名）；在企业代理之后就在启动 Claude Code 前设置 HTTPS_PROXY（见网络配置）；经 LLM 网关或中继时把 ANTHROPIC_BASE_URL 设为其地址；确保防火墙放行所需主机。

Unable to connect to Anthropic services

首次运行设置期间，Claude Code 在显示登录步骤之前检查能否到达 api.anthropic.com 和 platform.claude.com，任一失败就打印原因并退出（检查走的是与会话相同的代理配置）。怎么办：消息点名代理变量时，检查它的值指向正确的代理，并请网络团队放行经它到消息里主机的 HTTPS 连接；按上一条的检查逐项排查；网络开放而失败持续时，Claude Code 可能在你所在的国家或地区不可用。

Socket is closed

承载流式响应的连接在响应仍在到达时被关闭；最常见的原因是 Windows 上的企业代理在响应中途断开已建立的隧道。怎么办：用 claude update 更新到 v2.1.214 或更高，再重发消息；更新后在同一代理后仍持续失败，就按「Unable to connect to API」排查并检查网络配置里的代理设置。

API returned an empty or malformed response

Claude Code 对失败的流式请求做非流式重试，得到了 HTTP 成功状态，但响应体不是 Claude API 消息：常见是 HTML 错误页或登录页、空响应体、或另一种格式的 JSON；代理、网关或其他中间设备代替 API 作了回答。怎么办：读 Response: 子句看是哪个系统回答的（HTML 响应体、没有 Anthropic 请求 id、或点名了 nginx、cloudflare 之类的服务器，说明有中间设备代答）；经 LLM 网关时用直接请求测试这条路由，修好返回非 API 响应的那一跳；在有登录页的网络（如访客 Wi-Fi）里先在浏览器完成登录再重试；只有网关的非流式路由坏了时，见官方的网关兼容指南。

Streaming response ended before any complete data was received

来自你的模型服务商的流式响应完成了却没有交付任何可用数据，所以 Claude Code 不用流式重发请求来完成该回合；每个会话只在交互会话里显示一次警告。怎么办：把 Claude Code 与模型服务商之间的任何代理或网关配置成原样透传流式响应体及其头；Bedrock 上见「网关或代理后的流式错误」里对头和响应体的要求。

Bedrock streaming response has an unexpected content-type

Claude Code 与 Bedrock 之间的网关或代理在改写流式响应体或其 Content-Type 头（Bedrock 以 application/vnd.amazon.eventstream 流式返回），Claude Code 不去解码读不了的响应体。怎么办：配置网关原样透传 InvokeModelWithResponseStream 的响应体和 Content-Type 头（把流重新以 SSE 发出的中间层是常见原因）；设置 CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 只是隐藏这个错误，Claude Code 仍不会解码被改写头下的二进制响应体，这些请求会退回到较慢的非流式路径。

SSL certificate errors

你网络上的代理或安全设备用自己的证书拦截 TLS 流量，而 Claude Code 不信任它（v2.1.273 之前这两条消息都止于 Check your proxy or corporate SSL certificates，不带 OpenSSL 错误码）。怎么办：导出组织的 CA 证书包，用 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 让 Claude Code 使用它；完整设置见网络配置；不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0，那会完全关闭证书校验。

Host not allowed in a cloud session

云会话或 routine 发出的出站 HTTP 请求被环境的网络策略拦截；你还可能看到与目的地真实证书不符的 TLS 证书（云会话把出站流量经由强制执行策略的代理）。怎么办（这些步骤修改的是你自己的环境；组织共享的环境在选择器里是只读的，需要 Owner 从管理设置的「Cloud environments」页修改网络访问）：从 routine 表单或启动云会话的环境选择器里打开你的环境进行编辑；在「Edit cloud environment」对话框里把 Network access 从 Trusted 改为 Custom，并把被拦截的域名加到 Allowed domains（每行一个）。

请求错误

与请求内容相关：多数由 API 拒绝请求后返回，少数由 Claude Code 在发出请求之前本地产生。

Prompt is too long

对话加附件超出了模型的上下文窗口。交互会话里 Claude Code 显示的消息会建议 /compact 或 /clear（设置了 DISABLE_COMPACT 时只提 /clear）。怎么办：运行 /compact 总结较早的回合腾出空间，或 /clear 重新开始；/compact 回答 Not enough messages to compact. 说明对话只有一轮、没有可总结的更早内容，空间被这一个提示和 Claude Code 每次请求都发送的内容占满：运行 /clear 并用更少的粘贴文本或更小的附件重发，或减少工具定义和记忆文件；运行 /context 查看是什么占用了窗口（系统提示、工具、记忆、对话等）。

Context exceeds the token limit

对话已超出模型的上下文窗口时，/context 在输出顶部显示这条警告；在释放空间之前请求会以 Prompt is too long 失败（交互会话里表现为 Context limit reached 行）。怎么办：多轮对话里 /compact 总结较早回合，或 /clear 重新开始；v2.1.216 之前 /context 显示超过 100% 的用量而没有说明含义和恢复办法的警告行。

Request too large

原始请求体在分词之前就超过了 API 的 32MB 限制，通常因为大量粘贴内容、工具结果或附件；它与上下文窗口是两个不同的限制。怎么办：消息说 compacting cannot make it fit 时，按两次 Esc 退回到添加大内容的那一轮之前，或 /clear 重新开始；否则运行 /compact（它会丢弃累积的图片和附件）；用路径引用大文件而不是粘贴其内容，让 Claude 分块读取；图片问题见下一条。

Image was too large

粘贴或附加的图片超出 API 的大小或尺寸限制。Claude Code 用文本占位符替换无法处理的图片并重试，后续消息就成功了（2.1.142 之前被粘贴的图片可能留在对话里）。怎么办：粘贴前缩小图片——API 接受单张图片最长边最多 8000 像素，上下文里有很多图片时最长边 2000 像素；对相关区域截更紧的图，而不是全屏。

Unable to resize image

Claude Code 无法在发给 API 之前缩小附加的图片（通常大图会被自动缩放；这类错误表示图片无法解码或无法缩放到 API 限制之内）。怎么办：消息要你转换图片时，转成 PNG、JPEG、GIF 或 WebP 再附加（Claude Code 能从文件头验证这些格式的尺寸而无需解码）；消息报告尺寸或大小限制时，把图片缩小或重新压缩到限制以下；消息点名原因（如 CMYK JPEG、动画 WebP、可能损坏的文件）时，按消息建议的格式重新保存再附加。

PDF errors

附加的 PDF 无法处理（这里是非交互形式的消息，交互会话里会提示你按两次 Esc 重试）。怎么办：PDF 过大时，让 Claude 用 Read 工具读页范围而不是附加整个文件，或用 pdftotext 之类的工具提取文本并按路径引用输出文件；受保护或无效的 PDF 要去掉密码或从源应用重新导出；Read 工具读页范围可能因别的消息失败——页范围读取用 pdftoppm 渲染页面，按消息给的命令安装 poppler-utils。

Extra inputs are not permitted

Claude Code 与 API 之间的代理或 LLM 网关剥掉了 anthropic-beta 请求头，所以 API 拒绝了依赖它的字段（Claude Code 会连同 anthropic-beta 头一起发送 context_management、effort 之类仅 beta 的字段）。怎么办：配置网关转发 anthropic-beta 头（见功能透传里网关必须转发什么）；作为后备，启动前设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

Tool input schema is invalid

请求里某个工具声明的 input_schema 未通过 API 的 JSON Schema 校验，API 拒绝了整个请求；tools. 后面的数字是失败工具在请求工具列表里的位置，不是你能查到的名字。怎么办：Claude Code 早于 v2.1.216 就先 claude update；移除或禁用声明了无效 schema 的 MCP 服务器（v2.1.216+ 可在各服务器日志里找点名其输入 schema 会被拒绝的工具，没有日志点名就逐个禁用服务器）；你维护该服务器就修复工具的 input_schema（必须是有效 JSON Schema，且顶层属性名长度 1 到 64 个字符并只含允许的字符）。

Model is not a recognized model id

传给模型切换的字符串不是 Claude Code 能用作模型的，所以拒绝切换且不发请求，会话保持当前模型（通过 Agent SDK 的 setModel() 设置模型时也会出现）。怎么办：不带参数运行 /model 打开选择器，从你账号可用的模型里选，然后传选择器里显示的别名或 ID；用了只有较新 Claude Code 版本才支持的别名时运行 claude update，或传模型的完整 ID（服务器仍可能要求该模型的最低 Claude Code 版本）；v2.1.200 之前保存的模型不会被这项检查修复，陈旧值反复出现时从保存它的位置里删除。

Model not found

你按名称切换模型，Claude Code 无法确认存在该名称的模型（名称不是模型别名或 Claude Code 本地接受的其他写法时，会用最小 API 请求验证）。怎么办：不带参数运行 /model 并从你账号可用的模型里选，或用 sonnet 这样的别名（它解析到被维护的默认）；输入的是完整 ID 就对照你服务商的模型目录检查（新发布的模型可能先在 Anthropic API 上可用，之后你的服务商或区域才提供）；Agent SDK 里 setModel() 以此消息失败且会话继续用先前的模型，TypeScript SDK 可调用 supportedModels() 列出可用模型。

Claude Opus is not available with the Claude Pro plan

你当前订阅方案不包含所选模型（在 Claude Desktop 应用运行的会话里，消息说 sign out and sign in again 而不点名命令）。怎么办：运行 /model 选方案包含的模型；刚升级方案仍看到这条，就 /logout 再 /login——存储的令牌反映的是你登录时的方案，所以在 claude.ai 上升级不会在现有会话里生效，直到重新认证；各方案包含的模型见 claude.com/pricing。

Claude Code does not support this model

API 以 400 拒绝了请求，因为你的 Claude Code 版本低于所需的最低版本：你选的模型要求更新的版本（服务器按模型检查），或你组织的策略要求。怎么办：更新发出请求的那个二进制，然后开新会话；更新方式取决于二进制来源——你安装的 Claude Code 用 claude update；Claude 桌面应用更新应用；VS Code 扩展附带的二进制更新扩展；Agent SDK 包附带的二进制升级 SDK 包并重启你的应用（编译成单文件可执行程序的要重新构建）。

Model switch was blocked by a PreModelSwitch hook

PreModelSwitch Hook 没有批准你或客户端请求的模型切换，会话保持当前模型；切换来自 Agent SDK 宿主或 Remote Control 时，消息读作 Model switch blocked by a PreModelSwitch hook、不点名目标模型。冒号后的原因说明谁拒绝了：Hook 写的原因（满足它的要求，或选一个你的 Hook 允许的模型）；PreModelSwitch hook did not respond before its timeout（不在超时前应答的 Hook 会阻止切换，修好挂住的命令）。

thinking.type.enabled is not supported for this model

你的 Claude Code 版本低于所选模型的最低版本，CLI 发送了该模型不再接受的思考配置。怎么办：运行 claude update 并重启 Claude Code（官方列出了各模型所需的最低版本，如 Opus 4.7 需要 v2.1.111+、Opus 4.8 需要 v2.1.154+、Sonnet 5 需要 v2.1.197+、Opus 5 需要 v2.1.219+、Opus 5.5 需要 v2.1.280+、Sonnet 5.5 需要 v2.1.284+）；无法升级就 /model 选 Opus 4.6 或 Sonnet 4.6；在 Agent SDK 里遇到则升级 SDK 包（各模型要求的 TypeScript 和 Python SDK 版本见官方）。

Thinking budget exceeds output limit

配置的扩展思考预算超过了最大响应长度，没给实际回答留空间。怎么办：把 CLAUDE_CODE_MAX_OUTPUT_TOKENS 调到高于思考预算；思考预算与输出长度如何相互作用见扩展思考。

Tool use or thinking block mismatch

对话历史以不一致的状态到达 API：历史里 tool_use、tool_result、thinking 块的顺序与 API 期望的不符，所有变体含义相同。怎么办：用 Opus 4.7 或 Opus 4.8 时先 claude update（v2.1.156 之前在正常使用工具时就可能触发，且 /rewind 清除不了）；运行 /rewind 或按两次 Esc 退回到损坏回合之前的检查点并从那里继续（见检查点）。同类还有「Invalid data in redacted_thinking block」：API 以 400 拒绝了请求，因为它不能接受先前某回合里的 redacted_thinking 块。

Unsupported tool content removed

Claude Code 直连 Anthropic API 并加载或预览已保存的会话时，会移除 Anthropic API 不接受的工具内容，并在被移除内容位于两个思考块之间的位置留下这一行。怎么办：看到占位行不需要处理，会话继续、只是没有被移除的内容；恢复的会话每个回合都以 400 失败时，运行 claude update 再恢复会话（v2.1.246 之前不移除这些内容）。同类还有「role 'system' must precede an 'assistant' message」：API 以 400 拒绝，因为某条系统消息处在对话中它不接受的位置（Claude Code 把部分提醒和附件文本作为系统消息发送）。

Usage Policy refusal

API 拒绝回应，因为对话里的内容触发了使用政策检查；消息含 Request ID 和 Message ID，你认为拒绝有误时可向支持引用，并点名拒绝的模型。怎么办：按两次 Esc 或 /rewind 退回到触发拒绝的回合之前的检查点，换个说法或换一种做法；说不清是哪个回合引起的就 /clear 在同一项目里开新对话（之前的对话保留在磁盘上，仍可在 /resume 里找到）；非交互（-p）模式无法回退时，在不带 --continue 的新会话里用改写的提示重试。政策检查因模型而异。

Safety measures flagged a cybersecurity topic

模型的安全措施把对话里的内容标记为网络安全话题；消息点名标记请求的模型，并链接到 Cyber Verification Program（为正当的网络安全工作授予访问权限）。怎么办：工作确实需要这类内容就通过 Cyber Verification Program 申请访问；你的请求并非网络安全话题就运行 /feedback 上报误报；想在同一会话继续，按两次 Esc 或 /rewind 退回到触发标记的回合之前，换一种做法。

安装错误

出现在安装或更新 Claude Code 时（安装脚本、claude install、claude update）；安装期间的 command not found、PATH、权限和 TLS 问题见安装与登录故障排查。

Installation was killed before it could finish

安装脚本报告 claude install 步骤被信号终止；Linux 上退出码 137 表示进程收到 SIGKILL，在内存不足的主机上这通常是内核的 OOM killer。怎么办：停掉其他进程释放内存后重跑安装程序；增加交换空间或换更大的实例（见「低内存 Linux 服务器上安装被杀死」里创建交换文件的命令）。

The connection dropped while downloading the update

claude install 或 claude update 下载 Claude Code 二进制时到下载服务器的连接关闭，重试也没能恢复（连接断开、传输停滞、或下载的文件校验失败时 Claude Code 会重试下载）。怎么办：再运行一次 claude update（网络本身健康时下一次通常就成功；超时的消息要换一个更快或未被限速的网络再试）；网络要求代理就在运行安装程序或 claude update 之前设置 HTTPS_PROXY；企业代理一直关闭传输时，请网络团队放行从 downloads.claude.ai 的完整下载；从你的 shell 运行 claude doctor 检查安装。