报错原文索引
unsupported_country_region_territory
真实原因不是「你在的地区不能用」这么简单。详见 接入 DeepSeek 后端。
MCP 服务器
Section titled “MCP 服务器”MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry
JSON 配置里写了 url 但没写 type。Claude Code 把没有 type 的条目当 stdio 服务器处理。加上 type 字段即可。
command: expected string, received undefined
这是上一条报错在 v2.1.202 之前的措辞。看起来像是 command 字段的问题，实际是缺 type。
✘ Failed to connect（claude mcp list 状态）
配了 headers.Authorization 而服务端拒绝这个头时，Claude Code 报连接失败且不会回退到 OAuth。也可能是环境变量没展开——同一个输出里会有缺变量警告，把字面量 ${API_KEY} 当 token 发出去，服务端返回 401。
⏸ Pending approval（claude mcp list 状态）
.mcp.json 里的服务器需要你批准。交互式跑一次 claude 接受信任对话框。提交在项目 .claude/settings.json 里的 enableAllProjectMcpServers 在未信任的文件夹里被忽略。
! Needs authentication（claude mcp list 状态）
用 /mcp 面板或 claude mcp login <name> 走 OAuth。
以上全部详见 接 MCP 服务器。
subagent
Section titled “subagent”Subagent spawn limit reached
会话累计 subagent 数达到上限（默认 200，含已完成的）。/clear 重置计数，或调 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION。
Concurrent subagent limit reached
同时运行的 subagent 数达到上限（默认 20）。等运行数降下来，或调 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS。
这两个是不同的限额，错误信息相似但对应的变量不同。详见 subagent。
Budget limit reached
--max-budget-usd 的上限到了。subagent 的花费计入这个上限，且仍在运行的后台 subagent 会被停止。详见 放进脚本和 CI。
Did you mean claude update?
子命令拼错时 Claude Code 建议最接近的匹配并退出，不启动会话。
静默失败：不报错但也不生效
Section titled “静默失败：不报错但也不生效”这一类比报错更难查，因为没有任何输出提示你出了问题。
| 现象 | 原因 |
|---|---|
settings.json 里某个 key 完全没作用 | 那个 key 只认 ~/.claude.json（如 diffTool、autoConnectIde）。见配置优先级 |
"defaultMode": "auto" 不生效且不报错 | 项目层和 local 层的 auto 值被有意忽略，要写在 ~/.claude/settings.json。见权限模式 |
| 某一层设置整个没加载 | 那个文件 JSON 语法坏了。/status 的 Setting sources 里不会出现它，用 claude doctor 看解析错误 |
| 项目层 deny 规则没「覆盖」用户层 | 数组值是跨层合并的，不是覆盖。实际拦截范围是并集 |
| hook 完全不触发 | 针对 mcp__<server>__ 写的 matcher 对插件捆绑的 MCP 服务器不匹配，那些是 mcp__plugin_<plugin>_<server>__ |
| hook 脚本没拦住任何东西 | macOS / Linux 上忘了 chmod +x。没有执行权限的 hook 是失败而不是拦截 |
skill 的 /name 能用但 Claude 从不自动调用 | frontmatter YAML 坏了。Claude Code 加载正文但元数据为空，所以没有描述可匹配。用 --debug 看解析错误 |
| skill 在自动补全里不出现 | 它在启动目录下面的嵌套 .claude/skills/，Claude 碰过那个目录的文件之后才可用 |
| 改了 subagent 定义没生效 | 同一目录树下两个文件声明了同一个 name，加载哪个取决于文件系统读取顺序。/doctor 会报告 |
| subagent 缺了它该有的工具 | 后台运行的 subagent 内置工具集被二次收窄，移除时不报错。设 background: false 保留完整工具集。见subagent |
${CLAUDE_SKILL_DIR} 的 allow 规则永远匹配不上 | 需要 v2.1.129 或更高版本，旧版本上保持字面字符串 |
--json-schema 给了无效 schema 却拿到非结构化输出 | v2.1.205 之前不报错。升级后会直接报错退出 |
.claude/rules/ 里某条规则从不加载 | paths 里有无法解析的 glob（比如未转义的 [）。见CLAUDE.md 上下文工程 |
| Read 工具对一批文件莫名报错 | v2.1.207 之前，rules 里一个无效 glob 会让该规则求值过的每个文件都失败 |
| 权限比预期宽 | 可能有两份 settings.local.json（v2.1.211 位置变过），两份里的权限规则都生效 |
claude daemon status 变成了一句提示词 | claude 被别名成带 --dangerously-skip-permissions，且版本低于 v2.1.199 |
| 文档提到的标志报「未知参数」 | 先确认版本。claude --help 不列出全部标志，所以不在 --help 里不代表不可用 |
排查的通用顺序
Section titled “排查的通用顺序”不确定问题在哪一层时：
claude doctor—— 安装健康度和设置文件解析错误，不启动会话/status—— 看Setting sources确认哪些层真的加载了/context—— 看上下文里什么在占空间，确认 CLAUDE.md 和 skill 列表加载了/doctor—— 会话内检查，能给出精简建议claude --debug或--debug-file <path>—— 带类别过滤，如--debug "api,hooks"claude --safe-mode—— 关掉所有自定义，确认问题是否来自某个配置
第 6 步是二分法的起点：--safe-mode 下问题消失，说明是配置引起的，逐层打开找到那一项。