mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-06-12 20:37:08 -07:00
Merge troubleshooting into FAQ and spill over info into more reasonable places in the docs, eg error codes in the headless mode.
This commit is contained in:
Chris Williams
+11
-6
@@ -36,13 +36,18 @@ Returns a stream of newline-delimited JSON (JSONL) events.
|
||||
|
||||
## Exit codes
|
||||
|
||||
The CLI returns standard exit codes to indicate the result of the headless
|
||||
execution:
|
||||
The Gemini CLI uses specific exit codes to indicate the reason for termination.
|
||||
This is especially useful for headless scripting and automation:
|
||||
|
||||
- `0`: Success.
|
||||
- `1`: General error or API failure.
|
||||
- `42`: Input error (invalid prompt or arguments).
|
||||
- `53`: Turn limit exceeded.
|
||||
| Exit Code | Error Type | Description |
|
||||
| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| 0 | `Success` | Success. |
|
||||
| 1 | `GeneralError` | General error or API failure. |
|
||||
| 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) |
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
+2
-1
@@ -298,4 +298,5 @@ gemini -s -p "run shell command: mount | grep workspace"
|
||||
|
||||
- [Configuration](../reference/configuration.md): Full configuration options.
|
||||
- [Commands](../reference/commands.md): Available commands.
|
||||
- [Troubleshooting](../resources/troubleshooting.md): General troubleshooting.
|
||||
- [FAQ](../resources/faq.md): General troubleshooting and answers to common
|
||||
questions.
|
||||
|
||||
+2
-3
@@ -115,13 +115,12 @@ Deep technical documentation and API specifications.
|
||||
|
||||
Support, release history, and legal information.
|
||||
|
||||
- **[FAQ](./resources/faq.md):** Answers to frequently asked questions.
|
||||
- **[FAQ](./resources/faq.md):** Answers to frequently asked questions,
|
||||
including troubleshooting questions.
|
||||
- **[Quota and pricing](./resources/quota-and-pricing.md):** Limits and billing
|
||||
details.
|
||||
- **[Terms and privacy](./resources/tos-privacy.md):** Official notices and
|
||||
terms.
|
||||
- **[Troubleshooting](./resources/troubleshooting.md):** Common issues and
|
||||
solutions.
|
||||
- **[Uninstall](./resources/uninstall.md):** How to uninstall Gemini CLI.
|
||||
|
||||
## Development
|
||||
|
||||
+1
-1
@@ -16,5 +16,5 @@
|
||||
"/docs/index": "/docs",
|
||||
"/docs/quota-and-pricing": "/docs/resources/quota-and-pricing",
|
||||
"/docs/tos-privacy": "/docs/resources/tos-privacy",
|
||||
"/docs/troubleshooting": "/docs/resources/troubleshooting"
|
||||
"/docs/troubleshooting": "/docs/resources/faq"
|
||||
}
|
||||
|
||||
@@ -56,6 +56,94 @@ 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.
|
||||
|
||||
### Why am I getting 'You must be a named user on your organization's Gemini Code Assist Standard edition subscription' error?
|
||||
|
||||
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.
|
||||
|
||||
- **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:** Ask your Google Cloud administrator to add you to
|
||||
your organization's Gemini Code Assist subscription.
|
||||
|
||||
### Why am I getting a 'Failed to sign in. Message: Your current account is not eligible... because it is not currently available in your location' error?
|
||||
|
||||
Gemini CLI does not currently support your location. For a full list of
|
||||
supported locations, see the
|
||||
[Available locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
|
||||
page for Gemini Code Assist for individuals.
|
||||
|
||||
### Why am I getting a 'Failed to sign in. Message: Request contains an invalid argument' error?
|
||||
|
||||
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_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.
|
||||
|
||||
### Why am I getting an `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` or `unable to get local issuer certificate` error?
|
||||
|
||||
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.
|
||||
|
||||
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"`)
|
||||
|
||||
### Why am I getting an `EADDRINUSE` (Address already in use) error when starting an MCP server?
|
||||
|
||||
Another process is already using the port that the MCP server is trying to bind
|
||||
to. Either stop the other process that is using the port or configure the MCP
|
||||
server to use a different port.
|
||||
|
||||
### Why am I getting `MODULE_NOT_FOUND` or import errors?
|
||||
|
||||
Dependencies are not installed correctly, or the project hasn't been built.
|
||||
|
||||
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`.
|
||||
|
||||
### Why am I getting 'Operation not permitted' or 'Permission denied' errors?
|
||||
|
||||
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. Refer to the
|
||||
[Configuration: Sandboxing](../cli/sandbox.md) documentation for more
|
||||
information, including how to customize your sandbox configuration.
|
||||
|
||||
### Why isn't Gemini CLI running in interactive mode in my CI environment?
|
||||
|
||||
The Gemini CLI does not enter interactive mode (no prompt appears) if an
|
||||
environment variable starting with `CI_` (e.g., `CI_TOKEN`) is set. The
|
||||
underlying UI framework detects these variables and assumes a non-interactive CI
|
||||
environment. 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`.
|
||||
|
||||
### Why doesn't DEBUG mode work when I set it in my project's `.env` file?
|
||||
|
||||
The `DEBUG` and `DEBUG_MODE` variables are automatically excluded from project
|
||||
`.env` files to prevent interference with gemini-cli behavior. Use a
|
||||
`.gemini/.env` file instead, or configure the `advanced.excludedEnvVars` setting
|
||||
in your `settings.json` to exclude fewer variables.
|
||||
|
||||
## Installation and updates
|
||||
|
||||
### How do I check which version of Gemini CLI I'm currently running?
|
||||
@@ -78,6 +166,28 @@ If you installed it globally via `npm`, update it using the command
|
||||
the latest changes from the repository, and then rebuild using the command
|
||||
`npm run build`.
|
||||
|
||||
### Why am I getting a 'Command not found' error when attempting to run `gemini`?
|
||||
|
||||
Gemini CLI is not correctly installed or it is not in your system's `PATH`.
|
||||
|
||||
- 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`.
|
||||
|
||||
### Why am I seeing `npm WARN deprecated node-domexception@1.0.0` or `npm WARN deprecated glob` during install or update?
|
||||
|
||||
When installing or updating the Gemini CLI globally, you might see deprecation
|
||||
warnings regarding `node-domexception` or old versions of `glob`. These warnings
|
||||
occur because some dependencies rely on older package versions. Since Gemini CLI
|
||||
requires Node.js 20 or higher, the platform's native features are used, making
|
||||
these warnings purely informational. They are harmless and can be safely
|
||||
ignored. Your installation or update will complete successfully and function
|
||||
properly.
|
||||
|
||||
## Platform-specific issues
|
||||
|
||||
### Why does the CLI crash on Windows when I run a command like `chmod +x`?
|
||||
@@ -180,6 +290,35 @@ using your data to improve Google's machine learning models. See the
|
||||
[Gemini Code Assist for individuals privacy notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals)
|
||||
for more information.
|
||||
|
||||
## Debugging tips
|
||||
|
||||
### How do I debug issues with Gemini CLI?
|
||||
|
||||
- **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.
|
||||
|
||||
## Not seeing your question?
|
||||
|
||||
Search the
|
||||
|
||||
@@ -1,193 +0,0 @@
|
||||
# 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:
|
||||
- Gemini Code Assist for individuals:
|
||||
[Available locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
|
||||
|
||||
- **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](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` (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 (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.
|
||||
|
||||
- **Warning: `npm WARN deprecated node-domexception@1.0.0` or
|
||||
`npm WARN deprecated glob` during install/update**
|
||||
- **Issue:** When installing or updating the 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
|
||||
|
||||
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!
|
||||
|
||||
<!-- prettier-ignore -->
|
||||
> [!NOTE]
|
||||
> Issues tagged as "🔒Maintainers only" are reserved for project
|
||||
> maintainers. We will not accept pull requests related to these issues.
|
||||
@@ -228,10 +228,6 @@
|
||||
"label": "Terms and privacy",
|
||||
"slug": "docs/resources/tos-privacy"
|
||||
},
|
||||
{
|
||||
"label": "Troubleshooting",
|
||||
"slug": "docs/resources/troubleshooting"
|
||||
},
|
||||
{ "label": "Uninstall", "slug": "docs/resources/uninstall" }
|
||||
]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user