Skip to content
FunCoding

Search

Search docs, agents, posts, Skills and MCP servers

命令行与插件错误

claude 命令行及子命令、斜杠命令、Remote Control、claude import、MCP 命令、ultrareview、恢复会话、/tui 等错误；插件与市场的配置错误。

版本要求与措辞以官方为准。这里的错误来自 claude 命令行及其子命令、你在提示符提交的命令名、以及 /security-review 这类先运行 shell 命令收集上下文的命令，也来自重启 CLI 的 /tui。

命令行错误

  • --bg 与 --print 冲突（v2.1.198+）：你在同一次 claude 调用里同时用了 --bg 和 -p/--print。--bg 启动之后用 claude agents 附加的后台会话，而 --print 非交互运行、从不启动可附加的交互会话，所以二者不能合用。去掉其中一个。
  • Settings file exceeds the 2MiB limit：你传给 --settings 的文件超过 2 MiB，claude 在启动时以退出码 1 退出而不加载它（v2.1.214 之前不做大小检查，数 GB 的文件或 /dev/zero 这类设备文件会让内存暴涨）。把 --settings 指向小于 2 MiB 的普通 JSON 设置文件。
  • The current directory no longer exists：你从一个在 shell 进入之后被删除或移动的目录（如被另一个 shell 删掉的 worktree 或临时目录）启动了 claude，它无法读取工作目录，在会话开始前以退出码 1 退出。换到存在的目录再运行；目录在同一路径被重建但 shell 仍持有已删除的那个，运行 cd "$PWD" 或离开再重新进入；macOS 上遇到 EPERM 时用 Cmd+Q 退出终端应用再打开、回到该文件夹运行 claude，若 ls 仍失败就到「系统设置 > 隐私与安全性 > 文件和文件夹」给终端应用开启该文件夹。
  • Workspace not trusted when starting Remote Control：你在未受信任的目录里用 claude remote-control（别名 claude rc）启动 Remote Control 服务器模式，而命令无法询问你是否信任（如标准输入或输出不是终端）。先在终端里信任该目录：在那里运行 claude rc 并回答 y，或运行 claude 并接受工作区信任对话框，然后重新运行原命令；在主目录里就换到项目目录再启动。（v2.1.284 之前命令从不询问。）另有「Not carried over to the sessions Remote Control starts」：你在 remote-control 动词之前放了一个会限制或配置会话的全局 claude 标志，它不会带到 Remote Control 启动的会话里。
  • claude import is not yet available in this build：你运行了 claude import，Claude Code 发现导入流程被关闭，命令以退出码 1 退出（v2.1.222 之前把 import 当成提示并启动交互会话）。全新安装时先启动 claude、等会话加载、退出，再运行 claude import；功能开关拉取一直关闭的地方，自己设置配置：用 claude mcp add 添加 MCP 服务器，并创建要带过去的 CLAUDE.md、Skill 和命令、子智能体；消息还点名了 ~/.claude/settings.json——在 claude import 携带的配置里该文件只存权限模式，Claude Code 不从它读取 MCP 服务器。
  • Could not read Claude Code config：你运行 claude import 时 Claude Code 无法解析存放登录和各项目状态的 ~/.claude.json；子命令只读取该文件检查可用性，不显示交互会话里的恢复对话框。运行不带参数的 claude，它会检测到无效文件并提供重置，然后再运行 claude import；想保留你手动做的编辑，就用编辑器修好 ~/.claude.json 的 JSON 语法后重跑。
  • Could not import a server from Claude Desktop：claude mcp add-from-claude-desktop 里有一个你选中的服务器无法添加；命令仍导入其他选中的服务器，并为每个失败的打印一行（v2.1.205 之前第一个失败就中止整个导入）。把 claude_desktop_config.json 里的服务器改名为只含字母、数字、连字符和下划线，再重新运行；或用 claude mcp add、claude mcp add-json 以有效名称直接添加。
  • Cannot add MCP server to the managed scope：你用 --scope managed 运行了 claude mcp add 或 add-json；该作用域存放你组织通过 managedMcpServers 托管设置提供的服务器，Claude Code 只从托管设置读取，所以命令无法写入。把服务器加到你能写的作用域（local、user、project，不带 --scope 时用 local）；要给组织里每个用户提供，就把它加到你部署的托管设置里的 managedMcpServers。相关的「Can't read .mcp.json」：读取项目 .mcp.json 的命令（如带 --scope project 的 claude mcp add、claude mcp remove）发现当前目录里的该文件不是普通文件或过大。
  • MCP permission prompt tool not found：你传给 --permission-prompt-tool 的工具在运行首次需要权限决定时不在已连接的 MCP 工具里，要么其服务器从未连上，要么没有已连接服务器暴露该名称的工具。在同一目录运行 claude mcp list 确认服务器显示为已连接；确认工具名与服务器暴露的 mcp__<server>__<tool> 名称一致；服务器启动要超过 30 秒就调大 MCP_TIMEOUT。
  • OAuth callback port is already in use：向远程 MCP 服务器做 OAuth 登录时，Claude Code 启动本地监听器接收登录回调，若所需端口被别的进程占用，登录就以此消息失败（多发生在固定回调端口时）。运行消息里的命令找到占用端口的进程，停掉它或等它结束；别的程序需要永久占用该端口，就向服务器注册另一个重定向 URI，并用 MCP_OAUTH_CALLBACK_PORT 或 --callback-port 设置其端口；然后重新开始登录（如在 /mcp 里选该服务器）。
  • No available ports for OAuth redirect：Claude Code 无法为 OAuth 回调绑定本地端口。检查安全软件或沙箱策略是否阻止进程监听 127.0.0.1，允许 Claude Code 绑定本地端口，然后重新登录。另有「/security-review fails without origin/HEAD」：/security-review 用你的分支与 origin/HEAD（记录 origin 远端默认分支的本地引用）的 diff 构建评审上下文，该引用不存在时收集 diff 的 git 命令失败。
  • Input contained only whitespace：非交互模式下 Claude Code 拒绝完全由空格、制表符或换行组成的提示，因为 API 拒绝没有可见文本的消息；你看到哪条取决于空白提示来自哪里（命令行参数、stdin 等）。在提示里包含可见文本；脚本从变量或文件构建提示时，调用前检查来源不是空的。相关的「stream-json input carried over 256M characters with no newline」：你的程序在 claude -p --input-format stream-json 的 stdin 上发送了超过 268,435,456 个字符而没有换行，Claude Code 向 stderr 打印该错误并以退出码 1 退出，而不是继续缓冲（v2.1.257 之前会一直缓冲）。
  • Unknown command：在交互终端会话里你提交的 / 名称与本会话里任何命令都不匹配，Claude Code 报告该名称而不运行任何东西，并建议菜单里最接近的命令名或别名。运行建议的名称，或输入 / 加名称的一部分看本会话里有什么；Claude Code 把某个文档里有的命令报告为未知时，查看命令参考里该命令那一行点名的要求。
  • Diff is too large for ultrareview：你的分支与基准分支之间的 diff（含未提交和已暂存的改动）超过 ultrareview 的大小限制，所以 /code-review ultra 和 claude ultrareview 在云会话开始之前就拒绝评审。传一个更靠近你工作的基准分支（如 /code-review ultra develop）让评审只覆盖对该分支的 diff；或把改动拆成更小的分支分别评审（消息点名的文件贡献了最多的改动行，先把它们挪到自己的分支）。
  • Could not find merge-base with the base branch：ultrareview 需要两个分支共有的提交，git merge-base 找不到时拒绝评审。真正的基准是另一个分支就显式传：/code-review ultra <branch>；克隆可能没有完整历史时运行 git fetch --unshallow origin 再重跑。
  • Your checkout has no branches：检出可能有提交却没有分支（git init 后 git fetch <url> 再 git checkout FETCH_HEAD 会得到没有 refs 的分离 HEAD），Claude Code 把仓库打成 git bundle 上传做 ultrareview，没有分支就无法打包。用 git checkout -b <name> 在当前提交上创建分支再重跑。相关的「No GitHub account is connected to your Claude account」：你运行 /code-review ultra <PR> 时，Claude Code 在创建云会话之前询问服务器，连接到你 Claude 账号的 GitHub 账号能否访问该 PR 的仓库，没有连接账号或连接已过期，云端克隆会失败，所以拒绝启动（它不消耗免费次数也不计费）。
  • Failed to resume the conversation：Claude Code 无法读取或处理你从 claude --resume 选择器选的会话的已保存转录，于是结束进程而不是以部分加载的状态继续；消息里带着重试的命令。用消息里的会话 ID 运行 claude --resume <id> 重试；每次重试都同样失败就运行 claude update 再恢复（v2.1.275 之前的版本在转录里含它们读不了的条目时恢复失败）；仍失败就运行 claude 开新会话。
  • No conversation found with the session ID：你给 claude --resume <id> 传的会话 ID 没有匹配的已保存转录，Claude Code 显示消息后以退出码 1 退出（它先搜当前项目，再搜这台机器上的每个其他项目）。交互会话用 claude --resume 打开选择器并按 Ctrl+A 扩大到这台机器上的所有项目再选；用 claude -p 或 Agent SDK 创建的会话不出现在选择器里，要对照你原来那次运行打印的 session_id 重新核对 ID。另有 Windows 上的「读取该会话转录文件时报告 EBADF」错误。
  • Cannot switch renderers in this session：切换渲染器时 Claude Code 会重启其进程；你在它拒绝重启的会话里运行了 /tui，所以不切换也不保存任何东西，消息指出原因（如有工作在运行）。在没有这些限制的会话里运行 /tui fullscreen，或 /tui default 切回，Claude Code 会把 tui 设置保存在那里。相关的「Couldn't open Claude Desktop」：你运行 /desktop（别名 /app）或 claude --desktop，而 Claude Code 用来打开 Claude Desktop 的系统命令失败了（/desktop 后会话仍留在终端；claude --desktop 打印不带 Error: 前缀的消息并以状态 1 退出）。
  • Skill usage reports are not available on this connection：你从手机或浏览器经 Remote Control 运行了 /skill-doctor，Claude Code 不通过 Remote Control 发送 Skill 用量报告。在会话所在机器的终端里运行 /skill-doctor，或在那里运行 claude -p "/skill-doctor"。同类还有「Custom output styles can't be selected over Remote Control」：经 Remote Control 运行 /output-style 时，因为这样的回合可能不是账号所有者发起的，Claude Code 只列出并选择内置样式。

插件错误

来自插件和市场配置。没有产生本节消息的插件问题（如市场 URL 加载不了、插件装上了却没出现）见插件故障排查。

  • plugin eval is currently in early access：你运行 claude plugin eval 或 claude plugin eval init，它在做任何事之前以退出码 1 退出：第一条消息表示你的构建早于 v2.1.269（该命令正式可用的第一个版本）；第二条表示 Anthropic 在服务端关闭了该命令，本机没有任何办法重新打开。运行 claude --version 检查，并更新到更新的版本。
  • Marketplace is registered from an untrusted source：市场以保留给 Anthropic 官方市场的名称注册，但其注册来源不是 anthropics GitHub 仓库；Claude Code 每次加载或刷新市场时都重新检查保留名称。市场已注册就运行 claude plugin marketplace remove <name>，再从官方 github.com/anthropics 仓库重新添加；你发布的第三方市场在名称被保留之前就用了它，就改名并请用户从你的来源重新添加；保留名称列表见 Marketplace schema。相关的「Marketplace name is another spelling of a reserved name」：该名称本身不是保留名称，但 Claude Code 把它视为某个保留名称的另一种拼写。
  • Marketplace is already added from a different source：你通过 /plugin install <plugin> --marketplace <source> 确认添加市场，而从该来源取到的目录与你已从另一个来源添加的市场同名；Claude Code 保留已有的市场。已添加的就是你想要的，就按名称安装：/plugin install <plugin>@<marketplace>；想切到新来源，运行 /plugin marketplace remove <name> 再重试安装。相关的「Plugin command references user_config in a shell command」：插件的 Hook、monitor 或 MCP headersHelper 命令引用了 ${user_config.KEY} 插件选项，而替换后的字符串会传给 shell；配置值里含 $(...)、反引号或 ; 会作为代码运行，所以 Claude Code 拒绝运行。
  • Plugin archive integrity check failed：插件的市场条目用了带 sha256 固定的 archive 来源，下载文件的摘要与固定值不符，Claude Code 拒绝安装，插件缓存不变（文件被改动、条目的摘要过期、或链接被篡改三种可能）。你是发布者就对 URL 实际提供的文件重新计算摘要（shasum -a 256 my-plugin.zip，PowerShell 用 Get-FileHash -Algorithm SHA256 my-plugin.zip）并更新市场条目里的 sha256；你是安装者就运行 /plugin marketplace update <name> 刷新目录（条目可能已被更正）再重试；刷新后摘要仍不一致，安装前先问市场所有者他们固定的是哪个文件。
  • Path escapes plugin directory：插件的 plugin.json 或市场条目里声明的某个组件路径解析到了插件自己目录之外；Claude Code 丢弃该路径并加载插件的其余部分，消息里的组件名（如 commands、hooks）指出是哪一个。把引用的文件移进插件目录并用 ./ 相对路径指向它；路径是指向插件之外文件的符号链接就换成文件的副本；消息说路径含反斜杠就改用正斜杠（如 ./commands/deploy.md）；要与同一市场里的其他插件共享文件，在插件目录内用符号链接指向它们（遵循符号链接规则）。
  • Path could not be checked：Claude Code 问操作系统某个插件路径是否存在，得到的不是「未找到」而是别的错误，所以不加载该路径所指的内容；加载多少取决于哪个路径失败（插件的默认组件位置之一，还是显式声明的）。把指向自身的符号链接换成真实文件夹或删除；路径在网络挂载上就重新挂载共享；错误码是 EACCES 就恢复你对路径上方目录的执行权限；修好路径后运行 /reload-plugins 或重启 Claude Code 来加载插件或组件。（v2.1.265 之前 Claude Code 把无法检查的默认组件文件夹当作不存在，不带该组件地加载插件且没有错误。）
  • Marketplace entry path does not stay inside the marketplace directory：插件的市场条目声明了一个无法解析为市场自身目录之内位置的来源路径，所以插件不安装也不加载（绝对路径、向上爬出市场目录等都被拒绝）。你维护市场就把条目的 source 写成带正斜杠的普通相对路径（如 ./plugins/my-plugin），并保持它穿过的任何符号链接指向市场目录内部；市场是从直接 URL 添加的，相对条目无法解析，请市场作者改用别的插件来源，或改从它的 git 仓库添加。
  • Failed to load marketplace configuration：Claude Code 把你添加的插件市场保存在 ~/.claude/plugins/known_marketplaces.json 的注册文件里；需要注册表的插件命令（如 claude plugin install）在 Claude Code 无法使用它时以两种消息之一失败。打开该文件修复 JSON，或修正消息点名为不符合注册表 schema 的条目；修不好就删除文件或把内容换成 {}，再用 claude plugin marketplace add <source> 逐个重新添加市场（Claude Code 下次在你信任的文件夹里启动时，会重新注册你的用户或托管设置里 extraKnownMarketplaces 声明的市场）。相关的「Plugin is required by your organization」：你的组织要求某个插件，不能被禁用或卸载。