技术文档

主题

故障排除指南 ​

本指南提供常见问题的解决方案和调试技巧，包括以下主题：

  • 认证或登录错误
  • 常见问题解答 (FAQ)
  • 调试技巧
  • 查找类似的 GitHub Issues 或创建新 Issues

认证或登录错误 ​

  • 错误：You must be a named user on your organization's Gemini Code Assist Standard edition subscription to use this service. Please contact your administrator to request an entitlement to Gemini Code Assist Standard edition.

    • 原因： 如果 Gemini CLI 检测到定义了 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 环境变量，可能会出现此错误。设置这些变量会强制进行组织订阅检查。如果你使用的是未链接到组织订阅的个人 Google 账户，这可能会成为问题。
    • 解决方案：
      • 个人用户： 取消设置 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_PROJECT_ID 环境变量。检查并从你的 shell 配置文件（例如 .bashrc、.zshrc）和任何 .env 文件中删除这些变量。如果这不能解决问题，尝试使用不同的 Google 账户。
      • 组织用户： 联系你的 Google Cloud 管理员，将你添加到组织的 Gemini Code Assist 订阅中。

  • 错误：Failed to login. 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 密钥，它也包含单独的免费层。

  • 错误：UNABLE_TO_GET_ISSUER_CERT_LOCALLY 或 unable to get local issuer certificate

    • 原因： 你可能在具有拦截和检查 SSL/TLS 流量的防火墙的企业网络上。这通常需要 Node.js 信任自定义根 CA 证书。
    • 解决方案： 将 NODE_EXTRA_CA_CERTS 环境变量设置为你的企业根 CA 证书文件的绝对路径。
      • 示例：export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

常见错误消息和解决方案 ​

  • 错误：启动 MCP 服务器时出现 EADDRINUSE（地址已在使用中）。

    • 原因： 另一个进程已经在使用 MCP 服务器尝试绑定的端口。
    • 解决方案： 停止使用该端口的其他进程，或配置 MCP 服务器使用不同的端口。

  • 错误：尝试使用 gemini 运行 Gemini CLI 时出现命令未找到。

    • 原因： Gemini CLI 未正确安装或不在系统的 PATH 中。
    • 解决方案： 更新取决于你安装 Gemini CLI 的方式：
      • 如果你全局安装了 gemini，检查你的 npm 全局二进制目录是否在 PATH 中。你可以使用命令 npm install -g @google/gemini-cli@latest 更新 Gemini CLI。
      • 如果你从源代码运行 gemini，确保使用正确的命令调用它（例如 node packages/cli/dist/index.js ...）。要更新 Gemini CLI，从仓库拉取最新更改，然后使用命令 npm run build 重新构建。

  • 错误：MODULE_NOT_FOUND 或导入错误。

    • 原因： 依赖项未正确安装，或项目未构建。
    • 解决方案：
      1. 运行 npm install 确保所有依赖项都存在。
      2. 运行 npm run build 编译项目。
      3. 使用 npm run start 验证构建是否成功完成。

  • 错误："Operation not permitted"、"Permission denied" 或类似错误。

    • 原因： 启用沙箱时，Gemini CLI 可能尝试执行受沙箱配置限制的操作，例如在项目目录或系统临时目录之外写入。
    • 解决方案： 有关更多信息，包括如何自定义沙箱配置，请参阅 配置：沙箱 文档。

  • Gemini CLI 在 "CI" 环境中不以交互模式运行

    • 问题： 如果设置了以 CI_ 开头的环境变量（例如 CI_TOKEN），Gemini CLI 不会进入交互模式（不显示提示）。这是因为底层 UI 框架使用的 is-in-ci 包检测到这些变量并假定为非交互式 CI 环境。
    • 原因： is-in-ci 包检查 CI、CONTINUOUS_INTEGRATION 或任何带有 CI_ 前缀的环境变量的存在。当找到任何这些变量时，它表示环境是非交互式的，这会阻止 Gemini CLI 以交互模式启动。
    • 解决方案： 如果 CLI 功能不需要 CI_ 前缀的变量，你可以为命令临时取消设置它。例如：env -u CI_TOKEN gemini

  • DEBUG 模式无法从项目 .env 文件工作

    • 问题： 在项目的 .env 文件中设置 DEBUG=true 不会为 gemini-cli 启用调试模式。
    • 原因： DEBUG 和 DEBUG_MODE 变量会自动从项目 .env 文件中排除，以防止干扰 gemini-cli 行为。
    • 解决方案： 改用 .gemini/.env 文件，或在 settings.json 中配置 advanced.excludedEnvVars 设置以排除更少的变量。

退出代码 ​

Gemini CLI 使用特定的退出代码来指示终止原因。这对于脚本和自动化特别有用。

退出代码错误类型描述
41FatalAuthenticationError认证过程中发生错误。
42FatalInputError向 CLI 提供了无效或缺失的输入。（仅限非交互模式）
44FatalSandboxError沙箱环境（例如 Docker、Podman 或 Seatbelt）发生错误。
52FatalConfigError配置文件（settings.json）无效或包含错误。
53FatalTurnLimitedError达到会话的最大对话轮次。（仅限非交互模式）

调试技巧 ​

  • CLI 调试：

    • 使用 --debug 标志获取更详细的输出。
    • 检查 CLI 日志，通常位于用户特定的配置或缓存目录中。

  • 核心调试：

    • 检查服务器控制台输出中的错误消息或堆栈跟踪。
    • 如果可配置，增加日志详细程度。
    • 如果需要逐步执行服务器端代码，使用 Node.js 调试工具（例如 node --inspect）。

  • 工具问题：

    • 如果特定工具失败，尝试通过运行工具执行的命令或操作的最简单版本来隔离问题。
    • 对于 run_shell_command，首先检查命令是否直接在 shell 中工作。
    • 对于文件系统工具，验证路径是否正确并检查权限。

  • 预检检查：

    • 在提交代码之前始终运行 npm run preflight。这可以捕获许多与格式化、linting 和类型错误相关的常见问题。

查找类似的 GitHub Issues 或创建新 Issues ​

如果你遇到本故障排除指南中未涵盖的问题，请考虑搜索 Gemini CLI 的 GitHub Issue 跟踪器。如果找不到与你类似的问题，请考虑创建一个带有详细描述的新 GitHub Issue。也欢迎提交 Pull Request！

注意： 标记为 "🔒Maintainers only" 的 Issues 仅供项目维护者使用。我们不会接受与这些 Issues 相关的 Pull Request。

aicodex 文档网站

Copyright © 2025