gemini-cli/docs/troubleshooting.md

# Troubleshooting guide

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

- Authentication or login errors
- Frequently asked questions (FAQs)
- Debugging tips
- Existing GitHub Issues similar to yours or creating new Issues

## Authentication or login errors

- **Error:
  `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.`**
  - **Cause:** This error might occur if Gemini CLI detects the
    `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` environment variable is
    defined. Setting these variables forces an organization subscription check.
    This might be an issue if you are using an individual Google account not
    linked to an organizational subscription.

  - **Solution:**
    - **Individual Users:** Unset the `GOOGLE_CLOUD_PROJECT` and
      `GOOGLE_CLOUD_PROJECT_ID` environment variables. Check and remove these
      variables from your shell configuration files (for example, `.bashrc`,
      `.zshrc`) and any `.env` files. If this doesn't resolve the issue, try
      using a different Google account.

    - **Organizational Users:** Contact your Google Cloud administrator to be
      added to your organization's Gemini Code Assist subscription.

- **Error:
  `Failed to login. Message: Your current account is not eligible... because it is not currently available in your location.`**
  - **Cause:** Gemini CLI does not currently support your location. For a full
    list of supported locations, see the following pages:
    - Gemini Code Assist for individuals:
      [Available locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)

- **Error: `Failed to login. Message: Request contains an invalid argument`**
  - **Cause:** 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.
  - **Solution:** 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](http://aistudio.google.com/app/apikey), which also
    includes a separate free tier.

- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` or
  `unable to get local issuer certificate`**
  - **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.
  - **Solution:** First try setting `NODE_USE_SYSTEM_CA`; if that does not
    resolve the issue, set `NODE_EXTRA_CA_CERTS`.
    - Set the `NODE_USE_SYSTEM_CA=1` environment variable to tell Node.js to use
      the operating system's native certificate store (where corporate
      certificates are typically already installed).
      - Example: `export NODE_USE_SYSTEM_CA=1`
    - Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of
      your corporate root CA certificate file.
      - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt`

## Common error messages and solutions

- **Error: `EADDRINUSE` (Address already in use) when starting an MCP server.**
  - **Cause:** Another process is already using the port that the MCP server is
    trying to bind to.
  - **Solution:** Either stop the other process that is using the port or
    configure the MCP server to use a different port.

- **Error: Command not found (when attempting to run Gemini CLI with
  `gemini`).**
  - **Cause:** Gemini CLI is not correctly installed or it is not in your
    system's `PATH`.
  - **Solution:** The update depends on how you installed Gemini CLI:
    - 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`.
    - 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`.

- **Error: `MODULE_NOT_FOUND` or import errors.**
  - **Cause:** Dependencies are not installed correctly, or the project hasn't
    been built.
  - **Solution:**
    1.  Run `npm install` to ensure all dependencies are present.
    2.  Run `npm run build` to compile the project.
    3.  Verify that the build completed successfully with `npm run start`.

- **Error: "Operation not permitted", "Permission denied", or similar.**
  - **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](./cli/sandbox.md)
    documentation for more information, including how to customize your sandbox
    configuration.

- **Gemini CLI is not running in interactive mode in "CI" environments**
  - **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.
  - **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.
  - **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`

- **DEBUG mode not working from project .env file**
  - **Issue:** Setting `DEBUG=true` in a project's `.env` file doesn't enable
    debug mode for gemini-cli.
  - **Cause:** The `DEBUG` and `DEBUG_MODE` variables are automatically excluded
    from project `.env` files to prevent interference with gemini-cli behavior.
  - **Solution:** Use a `.gemini/.env` file instead, or configure the
    `advanced.excludedEnvVars` setting in your `settings.json` to exclude fewer
    variables.

## Exit codes

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        | `FatalAuthenticationError` | An error occurred during the authentication process.                                                |
| 42        | `FatalInputError`          | Invalid or missing input was provided to the CLI. (non-interactive mode only)                       |
| 44        | `FatalSandboxError`        | An error occurred with the sandboxing environment (e.g., Docker, Podman, or Seatbelt).              |
| 52        | `FatalConfigError`         | A configuration file (`settings.json`) is invalid or contains errors.                               |
| 53        | `FatalTurnLimitedError`    | The maximum number of conversational turns for the session was reached. (non-interactive mode only) |

## Debugging tips

- **CLI debugging:**
  - Use the `--debug` flag for more detailed output. In interactive mode, press
    F12 to view the debug console.
  - 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. For example, set the `DEBUG_MODE`
    environment variable to `true` or `1`.
  - 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.
  - 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:**
  - Always run `npm run preflight` before committing code. This can catch many
    common issues related to formatting, linting, and type errors.

## Existing GitHub issues similar to yours or creating new issues

If you encounter an issue that was not covered here in this _Troubleshooting
guide_, consider searching the Gemini CLI
[Issue tracker on GitHub](https://github.com/google-gemini/gemini-cli/issues).
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!

> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
> maintainers. We will not accept pull requests related to these issues.