故障排除指南

¥Troubleshooting guide

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

¥This guide provides solutions to common issues and debugging tips, including topics on:

• 身份验证或登录错误

  ¥Authentication or login errors

• 常见问题 (FAQ)

  ¥Frequently asked questions (FAQs)

• 调试技巧

  ¥Debugging tips

• 与您的问题类似的现有 GitHub 问题或创建新问题

  ¥Existing GitHub Issues similar to yours or creating new Issues

身份验证或登录错误

¥Authentication or login errors

• 错误：Failed to login. Message: Request contains an invalid argument

  ¥Error: Failed to login. Message: Request contains an invalid argument

• 拥有与 Gmail 帐户关联的 Google Workspace 帐户或 Google Cloud 帐户的用户可能无法激活 Google Code Assist 计划的免费套餐。

  ¥Users with Google Workspace accounts or Google Cloud accounts associated with their Gmail accounts may not be able to activate the free tier of the Google Code Assist plan.

• 对于 Google Cloud 帐户，您可以通过设置来解决此问题GOOGLE_CLOUD_PROJECT到您的项目 ID。

  ¥For Google Cloud accounts, you can work around this by setting GOOGLE_CLOUD_PROJECT to your project ID.

• 或者，您可以从谷歌人工智能工作室，其中还包括单独的免费套餐。

  ¥Alternatively, you can obtain the Gemini API key from Google AI Studio, which also includes a separate free tier.

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

  ¥Error: UNABLE_TO_GET_ISSUER_CERT_LOCALLY or unable to get local issuer certificate

• 原因：您可能位于一个装有防火墙的公司网络中，该防火墙会拦截并检查 SSL/TLS 流量。这通常需要自定义的根 CA 证书才能被 Node.js 信任。

  ¥Cause: You may be on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This often requires a custom root CA certificate to be trusted by Node.js.

• 解决方案：设置NODE_EXTRA_CA_CERTS环境变量为公司根 CA 证书文件的绝对路径。

  ¥Solution: Set the NODE_EXTRA_CA_CERTS environment variable to the absolute path of your corporate root CA certificate file.

  • 例子：export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

    ¥Example: export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

常见问题 (FAQ)

¥Frequently asked questions (FAQs)

• 问：如何将 Gemini CLI 更新到最新版本？

  ¥Q: How do I update Gemini CLI to the latest version?

• 答：如果您通过以下方式全局安装它npm，使用命令更新它npm install -g @google/gemini-cli@latest。如果您从源代码编译它，请从存储库中提取最新更改，然后使用命令重建npm run build。

  ¥A: If you installed it globally via npm, update it using the command npm install -g @google/gemini-cli@latest. If you compiled it from source, pull the latest changes from the repository, and then rebuild using the command npm run build.

• 问：Gemini CLI 配置或设置文件存储在哪里？

  ¥Q: Where are the Gemini CLI configuration or settings files stored?

• 答：Gemini CLI 配置存储在两个settings.json文件：

  ¥A: The Gemini CLI configuration is stored in two settings.json files:

  1. 在您的主目录中：~/.gemini/settings.json。

     ¥In your home directory: ~/.gemini/settings.json.

  2. 在项目的根目录中：./.gemini/settings.json。

     ¥In your project's root directory: ./.gemini/settings.json.

  参考Gemini CLI 配置了解更多详情。

  ¥Refer to Gemini CLI Configuration for more details.

• 问：为什么我在统计输出中看不到缓存的令牌计数？

  ¥Q: Why don't I see cached token counts in my stats output?

• 答：缓存令牌信息仅在使用缓存令牌时显示。此功能适用于 API 密钥用户（Gemini API 密钥或 Google Cloud Vertex AI），但不适用于 OAuth 用户（例如 Google 个人/企业帐户，例如 Google Gmail 或 Google Workspace）。这是因为 Gemini Code Assist API 不支持创建缓存内容。您仍然可以使用/statsGemini CLI 中的命令。

  ¥A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Gemini API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Gemini Code Assist API does not support cached content creation. You can still view your total token usage using the /stats command in Gemini CLI.

常见错误信息及解决方法

¥Common error messages and solutions

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

  ¥Error: EADDRINUSE (Address already in use) when starting an MCP server.

• 原因：另一个进程已在使用 MCP 服务器尝试绑定的端口。

  ¥Cause: Another process is already using the port that the MCP server is trying to bind to.

• 解决方案：停止正在使用该端口的其他进程或配置 MCP 服务器以使用其他端口。

  ¥Solution: Either stop the other process that is using the port or configure the MCP server to use a different port.

• 错误：未找到命令（当尝试使用gemini）。

  ¥Error: Command not found (when attempting to run Gemini CLI with gemini).

• 原因：Gemini CLI 未正确安装或不在您的系统中PATH。

  ¥Cause: Gemini CLI is not correctly installed or it is not in your system's PATH.

• 解决方案：更新取决于您安装 Gemini CLI 的方式：

  ¥Solution: The update depends on how you installed Gemini CLI:

  • 如果您安装了gemini在全球范围内，检查您的npm全局二进制目录位于您的PATH您可以使用以下命令更新 Gemini CLInpm install -g @google/gemini-cli@latest。

    ¥If you installed gemini globally, check that your npm global binary directory is in your PATH. You can update Gemini CLI using the command npm install -g @google/gemini-cli@latest.

  • 如果你正在跑步gemini从源代码中，确保使用正确的命令来调用它（例如，node packages/cli/dist/index.js ...)。要更新 Gemini CLI，请从存储库中提取最新更改，然后使用以下命令重建npm run build。

    ¥If you are running gemini from source, ensure you are using the correct command to invoke it (e.g., node packages/cli/dist/index.js ...). To update Gemini CLI, pull the latest changes from the repository, and then rebuild using the command npm run build.

• 错误：MODULE_NOT_FOUND或导入错误。

  ¥Error: MODULE_NOT_FOUND or import errors.

• 原因：依赖项未正确安装，或者项目尚未构建。

  ¥Cause: Dependencies are not installed correctly, or the project hasn't been built.

• 解决方案：

  ¥Solution:

  1. 跑步npm install以确保所有依赖项都存在。

     ¥Run npm install to ensure all dependencies are present.

  2. 跑步npm run build编译该项目。

     ¥Run npm run build to compile the project.

  3. 使用以下命令验证构建是否成功完成npm run start。

     ¥Verify that the build completed successfully with npm run start.

• 错误：“操作不允许”、“权限被拒绝”或类似信息。

  ¥Error: "Operation not permitted", "Permission denied", or similar.

• 原因：启用沙盒后，Gemini CLI 可能会尝试执行受沙盒配置限制的操作，例如在项目目录或系统临时目录之外写入。

  ¥Cause: When sandboxing is enabled, Gemini CLI may attempt operations that are restricted by your sandbox configuration, such as writing outside the project directory or system temp directory.

• 解决方案：请参阅配置：沙盒文档以获取更多信息，包括如何自定义沙盒配置。

  ¥Solution: Refer to the Configuration: Sandboxing documentation for more information, including how to customize your sandbox configuration.

• Gemini CLI 在“CI”环境中未以交互模式运行

  ¥Gemini CLI is not running in interactive mode in "CI" environments

• 问题：如果环境变量以CI_（例如，CI_TOKEN）已设置。这是因为is-in-ci底层 UI 框架使用的包检测这些变量并假设非交互式 CI 环境。

  ¥Issue: The Gemini CLI does not enter interactive mode (no prompt appears) if an environment variable starting with CI_ (e.g., CI_TOKEN) is set. This is because the is-in-ci package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment.

• 原因：这is-in-ci检查包是否存在CI，CONTINUOUS_INTEGRATION或任何带有CI_前缀。当发现其中任何一个时，都表示环境是非交互式的，这会阻止 Gemini CLI 以其交互模式启动。

  ¥Cause: The is-in-ci package checks for the presence of CI, CONTINUOUS_INTEGRATION, or any environment variable with a CI_ prefix. When any of these are found, it signals that the environment is non-interactive, which prevents the Gemini CLI from starting in its interactive mode.

• 解决方案：如果CI_CLI 运行不需要前缀变量，您可以暂时取消设置该命令。例如，env -u CI_TOKEN gemini

  ¥Solution: If the CI_ prefixed variable is not needed for the CLI to function, you can temporarily unset it for the command. e.g., env -u CI_TOKEN gemini

• 项目 .env 文件中的 DEBUG 模式不起作用

  ¥DEBUG mode not working from project .env file

• 问题：环境DEBUG=true在一个项目中.env文件没有为 gemini-cli 启用调试模式。

  ¥Issue: Setting DEBUG=true in a project's .env file doesn't enable debug mode for gemini-cli.

• 原因：这DEBUG和DEBUG_MODE变量自动从项目中排除.env文件以防止干扰 gemini-cli 行为。

  ¥Cause: The DEBUG and DEBUG_MODE variables are automatically excluded from project .env files to prevent interference with gemini-cli behavior.

• 解决方案：使用.gemini/.env文件，或者配置excludedProjectEnvVars在您的设置中settings.json排除更少的变量。

  ¥Solution: Use a .gemini/.env file instead, or configure the excludedProjectEnvVars setting in your settings.json to exclude fewer variables.

退出代码

¥Exit Codes

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

¥The Gemini CLI uses specific exit codes to indicate the reason for termination. This is especially useful for scripting and automation.

退出代码 ¥Exit Code	错误类型 ¥Error Type	描述 ¥Description
41 ¥41	FatalAuthenticationError ¥FatalAuthenticationError	身份验证过程中出现错误。 ¥An error occurred during the authentication process.
四十二 ¥42	FatalInputError ¥FatalInputError	向 CLI 提供的输入无效或缺失。（仅限非交互模式） ¥Invalid or missing input was provided to the CLI. (non-interactive mode only)
四十四 ¥44	FatalSandboxError ¥FatalSandboxError	沙盒环境（例如 Docker、Podman 或 Seatbelt）发生错误。 ¥An error occurred with the sandboxing environment (e.g., Docker, Podman, or Seatbelt).
52 ¥52	FatalConfigError ¥FatalConfigError	配置文件（settings.json) 无效或包含错误。 ¥A configuration file (settings.json) is invalid or contains errors.
53 ¥53	FatalTurnLimitedError ¥FatalTurnLimitedError	已达到会话的最大对话轮数。（仅限非交互模式） ¥The maximum number of conversational turns for the session was reached. (non-interactive mode only)

调试技巧

¥Debugging Tips

• CLI调试：

  ¥CLI debugging:

• 使用--verbose标志（如果可用）使用 CLI 命令来获取更详细的输出。

  ¥Use the --verbose flag (if available) with CLI commands for more detailed output.

• 检查 CLI 日志，通常位于用户特定的配置或缓存目录中。

  ¥Check the CLI logs, often found in a user-specific configuration or cache directory.

• 核心调试：

  ¥Core debugging:

• 检查服务器控制台输出中的错误消息或堆栈跟踪。

  ¥Check the server console output for error messages or stack traces.

• 如果可配置，则增加日志详细程度。

  ¥Increase log verbosity if configurable.

• 使用 Node.js 调试工具（例如，node --inspect) 如果您需要逐步执行服务器端代码。

  ¥Use Node.js debugging tools (e.g., node --inspect) if you need to step through server-side code.

• 工具问题：

  ¥Tool issues:

• 如果特定工具出现故障，请尝试通过运行该工具执行的命令或操作的最简单版本来隔离问题。

  ¥If a specific tool is failing, try to isolate the issue by running the simplest possible version of the command or operation the tool performs.

• 为了run_shell_command，请先检查该命令是否直接在您的 shell 中运行。

  ¥For run_shell_command, check that the command works directly in your shell first.

• 为了文件系统工具，验证路径是否正确并检查权限。

  ¥For file system tools, verify that paths are correct and check the permissions.

• 飞行前检查：

  ¥Pre-flight checks:

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

  ¥Always run npm run preflight before committing code. This can catch many common issues related to formatting, linting, and type errors.

与您的问题类似的现有 GitHub 问题或创建新问题

¥Existing GitHub Issues similar to yours or creating new Issues

如果您遇到本文未涵盖的问题故障排除指南，考虑搜索 Gemini CLIGitHub 上的问题跟踪器如果您找不到类似的问题，请考虑创建一个新的 GitHub Issue 并附上详细的描述。也欢迎提交 Pull 请求！

¥If you encounter an issue that was not covered here in this Troubleshooting guide, consider searching the Gemini CLI Issue tracker on GitHub. If you can't find an issue similar to yours, consider creating a new GitHub Issue with a detailed description. Pull requests are also welcome!