Skip to content
FunCoding

Search

Search docs, agents, posts, Skills and MCP servers

故障排查

Gemini CLI 的常见错误：登录与账号、证书错误、命令找不到、沙箱权限、CI 环境不进入交互模式、DEBUG 在 .env 里不生效。

认证或登录错误

  • You must be a named user on your organization's Gemini Code Assist Standard edition subscription...：原因是 Gemini CLI 检测到定义了 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 环境变量，设置它们会强制做组织订阅检查；如果你用的是没有关联组织订阅的个人 Google 账号就会出问题。解决：个人用户取消设置这两个环境变量（检查并从 shell 配置文件如 .bashrc、.zshrc 和任何 .env 文件里移除），仍不行就换一个 Google 账号；组织用户请联系 Google Cloud 管理员，把你加入组织的 Gemini Code Assist 订阅
  • Failed to sign in. Message: Your current account is not eligible... because it is not currently available in your location.：Gemini CLI 目前不支持你所在的位置，支持的位置列表见 Gemini Code Assist 的可用地区页
  • Failed to sign in. Message: Request contains an invalid argument：Google Workspace 账号或与 Gmail 账号关联的 Google Cloud 账号可能无法激活 Google Code Assist 计划的免费层。对 Google Cloud 账号，可以把 GOOGLE_CLOUD_PROJECT 设为你的项目 ID；或从 Google AI Studio 获取 Gemini API Key，它也有单独的免费层
  • UNABLE_TO_GET_ISSUER_CERT_LOCALLY 或 unable to get local issuer certificate：你可能在有防火墙拦截并检查 SSL/TLS 流量的公司网络里，这通常需要让 Node.js 信任自定义根 CA 证书。解决：先试设置 NODE_USE_SYSTEM_CA=1 让 Node.js 使用操作系统的原生证书存储（公司证书通常已装在那里）；不行再把 NODE_EXTRA_CA_CERTS 设为公司根 CA 证书文件的绝对路径

常见错误信息

  • 启动 MCP 服务器时 EADDRINUSE（地址已被占用）：另一个进程已在使用 MCP 服务器要绑定的端口；停掉那个进程，或把 MCP 服务器配置成用不同的端口
  • 用 gemini 运行时命令找不到：Gemini CLI 没有被正确安装或不在 PATH 里。全局安装时，检查 npm 全局二进制目录在你的 PATH 里，并可用 npm install -g @google/gemini-cli@latest 更新；从源码运行时，确认用了正确的命令调用（如 node packages/cli/dist/index.js ...），更新需要拉取最新改动并 npm run build 重新构建
  • MODULE_NOT_FOUND 或导入错误：依赖没装对，或项目没构建。运行 npm install、npm run build，并用 npm run start 验证构建成功
  • 「Operation not permitted」「Permission denied」等：启用沙箱时，Gemini CLI 可能尝试被沙箱配置限制的操作，如写到项目目录或系统临时目录之外，见「文件夹信任与沙箱」页
  • 在「CI」环境里 Gemini CLI 不进入交互模式：如果设置了名字以 CI_ 开头的环境变量（如 CI_TOKEN），Gemini CLI 不会进入交互模式（没有提示符出现）；如果该变量对 CLI 运行不需要，可以对该命令临时取消设置：env -u CI_TOKEN gemini
  • 项目 .env 里的 DEBUG 模式不生效：DEBUG 和 DEBUG_MODE 变量会自动从项目 .env 文件排除，以免干扰 gemini-cli 的行为；改用 .gemini/.env 文件，或配置 advanced.excludedEnvVars 设置排除更少的变量
  • 安装/更新时的 npm WARN deprecated node-domexception@1.0.0 或 glob 警告：一些依赖（或它们的子依赖，如 google-auth-library）依赖较旧的包版本。Gemini CLI 需要 Node.js 20 或更高，使用平台原生功能，所以这些警告只是信息性的，可以安全忽略

退出码与调试

Gemini CLI 用特定退出码指示终止原因，对脚本和自动化尤其有用（无头模式的退出码见「无头模式」页：0 成功、1 一般错误、42 输入错误、53 超出回合限制）。调试技巧：用 --debug（-d）运行以获得详细日志；官方页面末尾还列出了如何搜索已有的 GitHub issues 或新建 issue。卸载见官方「Uninstall」页。