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
-
Error:
Failed to login. Message: Request contains an invalid argument- 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.
- For Google Cloud accounts, you can work around this by setting
GOOGLE_CLOUD_PROJECTto 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_LOCALLYorunable 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: Set the
NODE_EXTRA_CA_CERTSenvironment variable to the absolute path of your corporate root CA certificate file.- Example:
export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt
- Example:
-
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
geminiglobally, check that yournpmglobal binary directory is in yourPATH. You can update Gemini CLI using the commandnpm install -g @google/gemini-cli@latest. - If you are running
geminifrom 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 commandnpm run build.
- If you installed
- Cause: Gemini CLI is not correctly installed or it is not in your
system's
-
Error:
MODULE_NOT_FOUNDor import errors.- Cause: Dependencies are not installed correctly, or the project hasn't been built.
- Solution:
- Run
npm installto ensure all dependencies are present. - Run
npm run buildto compile the project. - Verify that the build completed successfully with
npm run start.
- Run
-
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: 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 theis-in-cipackage, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment. - Cause: The
is-in-cipackage checks for the presence ofCI,CONTINUOUS_INTEGRATION, or any environment variable with aCI_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
- Issue: The Gemini CLI does not enter interactive mode (no prompt
appears) if an environment variable starting with
-
DEBUG mode not working from project .env file
- Issue: Setting
DEBUG=truein a project's.envfile doesn't enable debug mode for gemini-cli. - Cause: The
DEBUGandDEBUG_MODEvariables are automatically excluded from project.envfiles to prevent interference with gemini-cli behavior. - Solution: Use a
.gemini/.envfile instead, or configure theadvanced.excludedEnvVarssetting in yoursettings.jsonto exclude fewer variables.
- Issue: Setting
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) |
-
CLI debugging:
- Use the
--verboseflag (if available) with CLI commands for more detailed output. - Check the CLI logs, often found in a user-specific configuration or cache directory.
- Use the
-
Core debugging:
- Check the server console output for error messages or stack traces.
- Increase log verbosity if configurable.
- 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 preflightbefore committing code. This can catch many common issues related to formatting, linting, and type errors.
- Always run
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!