From 625ff6b27b30112a99c38b3ee6f44f742bb534c0 Mon Sep 17 00:00:00 2001 From: Chris Williams Date: Fri, 20 Mar 2026 11:53:02 -0700 Subject: [PATCH] Merge troubleshooting into FAQ and spill over info into more reasonable places in the docs, eg error codes in the headless mode. --- docs/cli/headless.md | 17 ++- docs/cli/sandbox.md | 3 +- docs/index.md | 5 +- docs/redirects.json | 2 +- docs/resources/faq.md | 139 +++++++++++++++++++++ docs/resources/troubleshooting.md | 193 ------------------------------ docs/sidebar.json | 4 - 7 files changed, 155 insertions(+), 208 deletions(-) delete mode 100644 docs/resources/troubleshooting.md diff --git a/docs/cli/headless.md b/docs/cli/headless.md index c83ce70d0e..aa41b87520 100644 --- a/docs/cli/headless.md +++ b/docs/cli/headless.md @@ -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 diff --git a/docs/cli/sandbox.md b/docs/cli/sandbox.md index b34433a878..3f6120bc6d 100644 --- a/docs/cli/sandbox.md +++ b/docs/cli/sandbox.md @@ -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. diff --git a/docs/index.md b/docs/index.md index af1915bb8f..c540ac65b2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 diff --git a/docs/redirects.json b/docs/redirects.json index 598f42cccf..7e544f1352 100644 --- a/docs/redirects.json +++ b/docs/redirects.json @@ -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" } diff --git a/docs/resources/faq.md b/docs/resources/faq.md index 8d1b42d032..8f49f6c160 100644 --- a/docs/resources/faq.md +++ b/docs/resources/faq.md @@ -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 diff --git a/docs/resources/troubleshooting.md b/docs/resources/troubleshooting.md deleted file mode 100644 index f490d41ffe..0000000000 --- a/docs/resources/troubleshooting.md +++ /dev/null @@ -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! - - -> [!NOTE] -> Issues tagged as "🔒Maintainers only" are reserved for project -> maintainers. We will not accept pull requests related to these issues. diff --git a/docs/sidebar.json b/docs/sidebar.json index 7198a0336b..11a68e0079 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -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" } ] }