ContextQMD
Back to Gemini Cli

Troubleshooting guide

docs/resources/troubleshooting.md

0.41.110.2 KB
Original Source

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 sign in. 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:

  • Error: Failed to sign in. 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, 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 (Windows PowerShell: $env: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 (Windows PowerShell: $env:NODE_EXTRA_CA_CERTS="C:\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 (for example, 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 documentation for more information, including how to customize your sandbox configuration.

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

    • Issue: Gemini CLI does not enter interactive mode (no prompt appears) if an environment variable starting with CI_ (for example, 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 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. For example, 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.

  • Warning: npm WARN deprecated [email protected] or npm WARN deprecated glob during install/update

    • Issue: When installing or updating Gemini CLI globally via npm install -g @google/gemini-cli or npm update -g @google/gemini-cli, you might see deprecation warnings regarding node-domexception or old versions of glob.
    • Cause: These warnings occur because some dependencies (or their sub-dependencies, like google-auth-library) rely on older package versions. Since Gemini CLI requires Node.js 20 or higher, the platform's native features (like the native DOMException) are used, making these warnings purely informational.
    • Solution: These warnings are harmless and can be safely ignored. Your installation or update will complete successfully and function properly without any action required.

Exit codes

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

Exit CodeError TypeDescription
41FatalAuthenticationErrorAn error occurred during the authentication process.
42FatalInputErrorInvalid or missing input was provided to the CLI. (non-interactive mode only)
44FatalSandboxErrorAn error occurred with the sandboxing environment (for example, Docker, Podman, or Seatbelt).
52FatalConfigErrorA configuration file (settings.json) is invalid or contains errors.
53FatalTurnLimitedErrorThe 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 (for example, 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 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!

<!-- prettier-ignore -->

[!NOTE] Issues tagged as "🔒Maintainers only" are reserved for project maintainers. We will not accept pull requests related to these issues.