---
title: "故障排查"
description: "Gemini CLI 常见故障排查：认证错误、地区限制、证书、PATH、MCP 端口、sandbox 权限、CI 环境和退出码。"
verifiedAt: "2026-05-09"
---

排查 Gemini CLI 不要先重装。先按错误类型定位：认证、网络、安装、配置、sandbox、CI。

> [!IMPORTANT]
> 排障顺序要从“当前命中了哪个 `gemini`、用了什么认证、读了哪些配置”开始。直接重装往往会保留旧配置，反而看不出根因。

## 排查总览

| 错误类型 | 第一检查项 | 常见根因 |
| --- | --- | --- |
| 登录失败 | 账号类型、`GOOGLE_CLOUD_PROJECT`、认证方式 | Workspace / Cloud 账号 entitlement 或项目变量不匹配 |
| 证书错误 | 企业代理、Node CA 配置 | TLS inspection 没有把公司根证书交给 Node |
| command not found | `command -v gemini`、npm global bin、PATH | 安装来源和 shell PATH 不一致 |
| import / module 错误 | 依赖、build、源码入口 | 源码环境未安装或未构建 |
| sandbox 拒绝 | 写入路径、被调用命令、sandbox 类型 | 试图访问项目外或受限路径 |
| CI 不交互 | `CI` / `CONTINUOUS_INTEGRATION` / `CI_*` 环境变量 | TUI 被判定为非交互环境 |

## 认证错误

如果看到 Gemini Code Assist Standard subscription 相关错误，先检查：

先用 `echo $GOOGLE_CLOUD_PROJECT` 和 `echo $GOOGLE_CLOUD_PROJECT_ID` 检查环境变量。

个人账号误设置这些变量，可能触发组织订阅检查。个人用户可以先 unset；组织用户需要管理员分配 entitlement。

## 地区不可用

如果登录提示当前账号所在地区不可用，需要查 Gemini Code Assist 支持地区。这个问题不是本地配置能修复的。

## 证书错误

企业网络或代理可能拦截 TLS，导致：

典型报错包括 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` 或 `unable to get local issuer certificate`。

官方 troubleshooting 的直接做法是把企业根证书交给 Node：

```bash
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt
```

如果公司网络要求统一代理，还要同时检查 shell、npm、Node 和 Gemini CLI 运行环境是否都走同一代理。不要把证书错误误判成 Gemini 账号错误。

## `gemini` command not found

检查安装方式和 PATH：

先看全局包、npm prefix 和 PATH：`npm list -g @google/gemini-cli`、`npm config get prefix`、`echo $PATH`。

如果是全局安装，更新命令是：

全局安装的更新命令是 `npm install -g @google/gemini-cli@latest`。

如果是源码运行，要确认使用的是源码入口，并且已经重新 build。普通用户教程不应默认走源码入口。

## `MODULE_NOT_FOUND` 或 import 错误

这类错误通常发生在源码开发或依赖损坏场景。先按官方建议恢复最小链路：

```bash
npm install
npm run build
npm run start
```

如果你只是普通用户，不要在业务项目里反复改 `package.json` 来修 Gemini CLI；先用全局安装或 `npx @google/gemini-cli` 在空目录复现。

## MCP 端口占用

`EADDRINUSE` 表示 MCP server 要绑定的端口已被占用。处理方式是停止占用进程，或给 MCP server 换端口。

## Sandbox 权限错误

`Operation not permitted` 或 `Permission denied` 在 sandbox 下常见。先判断 Gemini CLI 是否试图写项目外路径、系统临时目录以外路径，或调用被限制的命令。

## CI 环境不进交互模式

如果环境变量里存在 `CI`、`CONTINUOUS_INTEGRATION` 或 `CI_` 前缀变量，CLI 可能判断为非交互环境。

临时规避：

临时规避可以用 `env -u CI_TOKEN gemini`。

## DEBUG 不从项目 `.env` 生效

官方 troubleshooting 提到，项目 `.env` 里的 `DEBUG` 和 `DEBUG_MODE` 会被自动排除，避免干扰 Gemini CLI 行为。要打开 debug，优先使用 `.gemini/.env`，或明确调整 `settings.json` 里的 `advanced.excludedEnvVars`。

## 退出码

常见退出码：`41` 是认证错误，`42` 是输入错误，`44` 是 sandbox 错误，`52` 是配置错误，`53` 是 turn limit 错误。

| 退出码 | 含义 | 排查入口 |
| --- | --- | --- |
| `41` | 认证错误 | 登录方式、账号、project、API key |
| `42` | 输入错误 | headless 参数、stdin、非交互输入 |
| `44` | sandbox 错误 | Docker / Podman / Seatbelt、写入路径 |
| `52` | 配置错误 | 全局和项目 `settings.json` |
| `53` | turn limit | 任务拆分、上下文、自动化循环 |

## 最小复现

排障记录要能复跑：

1. 在空目录执行同一命令。
2. 记录 `gemini --version` 和 `command -v gemini`。
3. 标注认证方式，不贴 token。
4. 临时移开项目 `.gemini/` 后复测。
5. 如果涉及 MCP、hooks 或 shell，单独验证底层命令是否可运行。

## 下一步

<Cards>
  <Card title="卸载" description="确认是安装包或缓存问题后，再按安装来源卸载。" href="/docs/gemini-cli/official/08-troubleshooting-reference/82-uninstall" />
  <Card title="Sandbox" description="权限错误和隔离问题回到 sandbox 页面。" href="/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
  <Card title="MCP setup" description="MCP 端口、启动和配置问题回到 MCP setup。" href="/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
</Cards>

## 官方来源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
- [Gemini CLI troubleshooting guide](https://google-gemini.github.io/gemini-cli/docs/troubleshooting.html)
