Gemini CLI Not Working? A Complete Troubleshooting Handbook

Introduction

There is a specific kind of frustration that comes from a broken developer tool. Unlike a bug in your own code — where you have full visibility into the source, the stack trace, and the system state — a broken CLI tool sits in a black box. You type a command, and instead of the output you expected, you get a cryptic error message, a silent hang, or nothing at all. Debugging someone else's tool, against a remote API, across a network you do not control, feels like detective work without a crime scene.

Gemini CLI, for all its power, is not immune to this class of problem. It is a client for a remote AI service, which means the failure surface is wider than a purely local tool. Something can go wrong with your API key, with your local network, with the Google AI quota attached to your account, with your system's Node.js installation, with the CLI binary itself, or with the remote service. Each failure mode looks different, and each requires a different fix.

This handbook is the reference I wish had existed when I first started hitting issues with Gemini CLI. It covers every significant failure category I have encountered across months of daily use: authentication errors, network problems, rate limiting, process crashes, and configuration conflicts. For each category, you will find diagnostic commands you can run right now, an explanation of the root cause, and a concrete step-by-step solution.

No matter what is going wrong with your Gemini CLI installation, start at the Quick Diagnostic Checklist below. It resolves the majority of issues in under five minutes.

---

TL;DR

• Authentication issues are the most common failure. Run gemini --version and echo $GEMINI_API_KEY first to confirm the basics.
• Rate limit errors (429) require exponential backoff — never hammer the API with retries.
• Hangs and crashes are almost always caused by a corrupted config file, an incompatible Node.js version, or a runaway subprocess.
• Configuration conflicts happen when environment variables override your settings file silently.
• When in doubt, run gemini with the --debug flag — it exposes the full request/response lifecycle.
• Most issues resolve by: (1) confirming the API key is valid, (2) checking your network, (3) clearing the config cache, and (4) reinstalling the CLI.

---

Quick Diagnostic Checklist

Before diving into any specific error, run through this five-step checklist. It takes less than three minutes and resolves roughly 70% of Gemini CLI issues without further investigation.

Step 1: Confirm the CLI Is Installed and Accessible

gemini --version

If this command is not found, the binary is either not installed or not on your PATH. Install or reinstall:

npm install -g @google/gemini-cli
# or with npx (no install required)
npx @google/gemini-cli --version

If npm install -g fails with a permission error, either fix your npm global prefix directory or use a Node version manager like nvm — never sudo npm install -g.

Step 2: Verify the API Key Is Set

echo $GEMINI_API_KEY

The output should be a non-empty string starting with AIza. If it is empty, set it:

export GEMINI_API_KEY="your-api-key-here"

Add this line to your shell profile (.zshrc, .bashrc, or .bash_profile) for persistence across sessions.

Step 3: Test Raw API Connectivity

Bypass the CLI entirely to confirm your key and network can reach the API:

curl -s "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY" \
  | head -c 200

A successful response starts with {"models":. Any other output — a connection error, an HTML page, or a JSON error object — tells you whether the problem is with your key, your network, or the remote service.

Step 4: Check for Config File Corruption

cat ~/.gemini/settings.json

If the file exists, paste its contents into a JSON validator (or run python3 -m json.tool ~/.gemini/settings.json). A syntax error in this file causes silent failures or unexpected behaviour that is difficult to trace.

Step 5: Run with Debug Output

gemini --debug "hello"

The --debug flag exposes the full HTTP request, response status codes, timing, and any internal error messages. Most problems become immediately obvious once you can see the raw communication between the CLI and the API.

If all five steps pass and the problem persists, proceed to the relevant section below.

---

Authentication Errors

Authentication is the most common failure category, and it has several distinct causes.

API Key Not Found or Invalid

Symptoms: Error messages like API key not found, INVALID_ARGUMENT: API key not valid, or 403 Forbidden.

Root causes:

• The GEMINI_API_KEY environment variable is not set in the current shell session.
• The key was set in one terminal but not inherited by a new one.
• The key contains whitespace or invisible characters from copy-paste.
• The key was deleted or regenerated in Google AI Studio without updating the local environment.

Diagnosis:

# Check the variable is set and print its length
echo "Key length: ${#GEMINI_API_KEY}"
echo "Key prefix: ${GEMINI_API_KEY:0:10}"

# Verify the key is accepted by the API
curl -s "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY" \
  | python3 -m json.tool 2>/dev/null | head -5

Fix:

1. Regenerate the API key at aistudio.google.com if you suspect it was rotated.
2. Set it cleanly without trailing whitespace:

# Use a here-string to avoid accidental newline
export GEMINI_API_KEY=$(echo -n "your-key-here")

3. Persist it properly in your shell profile:

# Add to ~/.zshrc or ~/.bashrc
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc

Permission Errors (403)

Symptoms: 403 Forbidden, PERMISSION_DENIED, or User does not have sufficient permissions.

Root causes:

• The API key belongs to a Google Cloud project that has not enabled the Generative Language API.
• The key is scoped to specific IP addresses that do not include your current IP.
• You are attempting to access a model tier (e.g., gemini-2.5-pro) that requires billing to be enabled.

Fix:

1. Go to console.cloud.google.com and navigate to APIs & Services > Library.
2. Search for "Generative Language API" and ensure it is enabled for your project.
3. If you use API key restrictions, temporarily remove IP restrictions to confirm that is the cause.
4. Enable billing for your project if you are trying to use a paid model tier.

Quota Exhausted (Before Rate Limiting)

Symptoms: 429 Resource has been exhausted, or RESOURCE_EXHAUSTED immediately — even on the first request of the day.

This is distinct from transient rate limiting. Quota exhaustion means you have consumed your entire monthly allocation.

Diagnosis:

Check your usage dashboard: console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas

Fix:

• Request a quota increase through the Google Cloud console.
• Switch to a different API key attached to a project with remaining quota.
• If you are on the free tier, consider upgrading to a paid tier for higher limits.

---

Connection Issues

Network problems are the second most common cause of Gemini CLI failures, and they are often misdiagnosed as authentication errors because both can produce similar-looking output.

Network Timeouts

Symptoms: The CLI hangs for 30–60 seconds and then prints ETIMEDOUT, ECONNRESET, or ENOTFOUND generativelanguage.googleapis.com.

Diagnosis:

# Test basic connectivity to Google's infrastructure
ping -c 4 generativelanguage.googleapis.com

# Test HTTPS connectivity on port 443
curl -v --max-time 10 https://generativelanguage.googleapis.com 2>&1 | tail -20

# Check if DNS resolves correctly
nslookup generativelanguage.googleapis.com

Fix:

1. DNS issues: Try switching to a public DNS resolver temporarily:

# macOS: add to /etc/resolv.conf (temporary) or change in System Settings > Network
nameserver 8.8.8.8
nameserver 1.1.1.1

2. Firewall blocking: Check whether your corporate firewall or security software is blocking outbound connections to generativelanguage.googleapis.com on port 443. You may need to whitelist this domain.

3. Timeout tuning: If your network is legitimately slow, you can increase the timeout via an environment variable (check the CLI documentation for the current flag name, as this may vary by version):

GEMINI_TIMEOUT=120000 gemini "your prompt"

Proxy Configuration

If you work behind a corporate HTTP proxy, the CLI may not be picking up your proxy settings automatically.

Symptoms: Timeouts or connection errors in a corporate environment, but the same CLI works on a home network.

Fix:

# Set standard proxy environment variables
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"

# Node.js applications respect these variables natively
# Verify by running the curl diagnostic through the proxy:
curl --proxy "$HTTPS_PROXY" https://generativelanguage.googleapis.com

If your proxy uses certificate inspection (man-in-the-middle TLS), you will also need to configure the custom CA certificate:

export NODE_EXTRA_CA_CERTS="/path/to/your/corporate-ca.crt"

TLS Certificate Errors

Symptoms: UNABLE_TO_VERIFY_LEAF_SIGNATURE, certificate has expired, or SSL_ERROR_RX_RECORD_TOO_LONG.

Fix:

1. Update your Node.js installation — outdated Node.js ships with an outdated certificate store.
2. If the error is from a corporate proxy, set NODE_EXTRA_CA_CERTS as shown above.
3. Never set NODE_TLS_REJECT_UNAUTHORIZED=0 in production — this disables all certificate verification and exposes you to man-in-the-middle attacks. It is acceptable only for temporary local debugging.

---

Rate Limit Errors

Rate limiting is a natural constraint of using any shared API service. Understanding how it works — and how to work with it rather than against it — is essential for sustained productivity with Gemini CLI.

Understanding 429 Errors

When the API returns HTTP 429, it includes information about which quota was exceeded. There are two distinct limits:

• Requests Per Minute (RPM): How many API calls you can make per 60-second window.
• Tokens Per Minute (TPM): How many input + output tokens the API will process per 60-second window.

You can hit the TPM limit even with a low request count if your prompts are large. This is common when feeding large files as context.

Symptoms:

Error: 429 Too Many Requests
Quota exceeded for quota metric 'generate_content_request_count'

Implementing Backoff Strategy

Never retry a 429 immediately. The correct pattern is exponential backoff with jitter:

#!/bin/bash
# retry-gemini.sh — exponential backoff wrapper for gemini CLI

MAX_RETRIES=5
INITIAL_DELAY=2
PROMPT="$*"

attempt=0
delay=$INITIAL_DELAY

while [ $attempt -lt $MAX_RETRIES ]; do
  output=$(gemini "$PROMPT" 2>&1)
  exit_code=$?

  if [ $exit_code -eq 0 ]; then
    echo "$output"
    exit 0
  fi

  if echo "$output" | grep -q "429"; then
    attempt=$((attempt + 1))
    # Add jitter: delay + random(0, delay)
    jitter=$((RANDOM % delay))
    total_delay=$((delay + jitter))
    echo "Rate limited. Retry $attempt/$MAX_RETRIES in ${total_delay}s..." >&2
    sleep $total_delay
    delay=$((delay * 2))
  else
    # Non-rate-limit error: do not retry
    echo "$output"
    exit $exit_code
  fi
done

echo "Max retries exceeded." >&2
exit 1

The key principles: start with a small delay, double it on each retry, add random jitter to avoid thundering-herd problems when multiple clients retry simultaneously, and cap the maximum number of retries.

Reducing Token Consumption

If you frequently hit TPM limits, the most effective strategy is reducing the tokens you send per request:

1. Be specific with file context. Instead of feeding entire files, extract only the relevant functions:

# Instead of:
gemini "explain this" < large_file.py

# Extract just what you need:
sed -n '50,120p' large_file.py | gemini "explain this function"

2. Use the lighter model for simple tasks. gemini-2.0-flash has higher free-tier rate limits than gemini-2.5-pro and is sufficient for many tasks:

gemini --model gemini-2.0-flash "summarize this log" < error.log

3. Batch related questions. Combining multiple related questions into a single prompt is more token-efficient than sending them sequentially.

Monitoring Your Quota

Check your quota usage proactively to avoid surprises:

# View current quota metrics via the Cloud API
curl -s "https://serviceusage.googleapis.com/v1/projects/YOUR_PROJECT_ID/services/generativelanguage.googleapis.com" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  | python3 -m json.tool | grep -A 3 "quotaLimit"

Set up budget alerts in the Google Cloud console at a low threshold (e.g., $5) so you receive email notifications before costs escalate.

---

CLI Crashes and Hangs

Process-level failures — where the CLI freezes indefinitely or exits with a non-zero code and no meaningful message — are the most frustrating to debug because the error is not in your prompt or your key. It is in the execution environment itself.

Diagnosing a Hanging Process

If the CLI hangs and does not respond to Ctrl+C:

# Find the process ID
ps aux | grep gemini

# Force kill it
kill -9 <PID>

After killing it, try the command again with --debug to see exactly where execution stalls. Hangs almost always occur at one of these points:

1. During authentication: The CLI is waiting for a browser OAuth flow to complete.
2. During a large request: The initial response is delayed. Try reducing the prompt size.
3. During a shell tool execution: A subprocess launched by the CLI is itself hanging.

Node.js Version Incompatibility

Gemini CLI requires a minimum Node.js version. Running it on an older version produces unpredictable behaviour — sometimes silent crashes, sometimes garbled output, sometimes hangs.

Diagnosis:

node --version
# Check the CLI's documented minimum version (currently Node 18+)

Fix:

Install a current LTS version of Node.js. If you manage multiple Node.js versions, use nvm:

nvm install --lts
nvm use --lts
# Reinstall the CLI under the new version
npm install -g @google/gemini-cli

Memory Exhaustion

When feeding very large files (tens of thousands of lines), the CLI process can exceed Node.js's default heap limit.

Symptoms: JavaScript heap out of memory, ENOMEM, or the process exits without any message.

Fix:

Increase the Node.js heap limit by setting NODE_OPTIONS:

export NODE_OPTIONS="--max-old-space-size=4096"
gemini "summarize this" < enormous_file.txt

This sets the heap to 4 GB. Adjust the value based on your available RAM.

For a more sustainable fix, avoid feeding entire large files at once. Use head, tail, or sed to extract the relevant portion before passing it to the CLI.

Corrupted Installation

If the CLI produces unexpected JavaScript errors on startup (stack traces mentioning internal modules), the installation is likely corrupted.

Fix:

# Full clean reinstall
npm uninstall -g @google/gemini-cli
npm cache clean --force
npm install -g @google/gemini-cli

---

Configuration Problems

Configuration issues are particularly insidious because they do not produce error messages — the CLI runs successfully, but does not behave as expected.

Settings File Not Being Read

The CLI looks for a project-level settings file at .gemini/settings.json in the current working directory (or a parent directory). If you have this file but settings are not being applied, confirm:

1. The file path is exactly .gemini/settings.json (note: no dot prefix on the directory name in most shells — it is a hidden directory named .gemini).
2. The JSON syntax is valid.
3. You are running gemini from within or below the directory containing .gemini/.

# Verify the file is found
ls -la .gemini/
python3 -m json.tool .gemini/settings.json

Environment Variables Silently Overriding Config

Environment variables take precedence over the settings file. If a setting in your .gemini/settings.json seems to be ignored, check whether a conflicting environment variable is set:

# Print all Gemini-related environment variables
env | grep -i gemini

Common conflicts:

• GEMINI_MODEL overrides the model field in settings.json.
• GEMINI_API_KEY will always be used if set, regardless of any auth configuration file.

To temporarily disable all Gemini environment variables and test against your settings file only:

env -u GEMINI_MODEL -u GEMINI_API_KEY gemini --debug "test"

Multiple Config Files in Conflict

The CLI can read from multiple configuration locations: a global config in ~/.gemini/settings.json and a project-level config in ./.gemini/settings.json. The project-level config takes precedence, but only for keys that are explicitly set in it.

If you have unexpected behaviour, check both locations:

# Global config
cat ~/.gemini/settings.json

# Project config (run from your project root)
cat .gemini/settings.json

Best practice: Keep your global config minimal (just your preferred theme and editor settings) and put all project-specific settings in the project-level file. This makes the active configuration predictable and auditable.

GEMINI.md Not Being Loaded

If your project context file (GEMINI.md) does not seem to be affecting the model's behaviour, confirm:

1. The file is named exactly GEMINI.md (uppercase, no extension variants).
2. The contextFileName field in settings.json matches the actual filename if you customised it.
3. The file is in the root of your project, not a subdirectory.

# Confirm the context file exists and is readable
ls -la GEMINI.md
wc -l GEMINI.md

# Check if settings.json references a custom name
cat .gemini/settings.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('contextFileName','GEMINI.md'))"

---

Error Code Reference Table

| Error Code | HTTP Status | Category | Common Cause | First Fix to Try | |---|---|---|---|---| | INVALID_ARGUMENT | 400 | Authentication | API key has incorrect format or request is malformed | Verify key format; check request payload with --debug | | UNAUTHENTICATED | 401 | Authentication | API key is missing or not recognised | Re-export GEMINI_API_KEY; regenerate the key | | PERMISSION_DENIED | 403 | Authentication | Generative Language API not enabled; billing not set up | Enable API in Cloud Console; set up billing | | NOT_FOUND | 404 | Configuration | Model name is invalid or does not exist for your region | Check available models; confirm region availability | | RESOURCE_EXHAUSTED | 429 | Rate Limiting | Per-minute or monthly quota exceeded | Wait and retry with backoff; check quota dashboard | | INTERNAL | 500 | Server Error | Transient Google-side failure | Wait 30–60 seconds and retry; check status.cloud.google.com | | UNAVAILABLE | 503 | Server Error | Google AI service temporarily down | Check status page; retry with backoff | | DEADLINE_EXCEEDED | 504 | Timeout | Request took longer than the server's timeout limit | Reduce prompt/context size; try a faster model | | ETIMEDOUT | N/A | Network | TCP connection to API endpoint timed out | Check firewall, DNS, proxy settings | | ENOTFOUND | N/A | Network | DNS resolution failed for generativelanguage.googleapis.com | Check internet connectivity; try alternate DNS | | ECONNRESET | N/A | Network | Connection dropped mid-stream | Retry; check for unstable network or proxy interference | | heap out of memory | N/A | Local | Node.js process exceeded memory limit | Set NODE_OPTIONS=--max-old-space-size=4096 |

---

When to File a Bug Report

Most issues with Gemini CLI are configuration or environment problems, not bugs. Before opening a GitHub issue, work through the entire Quick Diagnostic Checklist and the relevant section of this handbook. That said, there are genuine bugs, and they are worth reporting when found.

Signs That You Have Found a Genuine Bug

• The issue reproduces consistently on a clean machine with a fresh install.
• The --debug output shows the CLI sending an incorrect or malformed request that you did not cause.
• The CLI crashes with a JavaScript stack trace that points to internal CLI code (not your input).
• A feature documented in the official docs does not work as described, and the behavior is not explainable by your config.
• The issue was not present in a previous version — you can confirm this by installing the old version and testing.

How to Write a Useful Bug Report

A well-written bug report gets fixed faster. Include all of the following:

1. Environment information:

# Paste the output of these commands into your report
gemini --version
node --version
npm --version
uname -a          # macOS/Linux
# or:
ver               # Windows

2. A minimal reproducible example. Strip down your use case to the smallest possible input that still triggers the bug. If the bug happens with a 5000-line file, try to find the minimum context that reproduces it. A bug report with a 10-line reproducer gets fixed; a bug report with "here is my 5000-line codebase" often does not.

3. Exact error output. Copy the full terminal output, including the command you ran. Use code blocks in your GitHub issue. Truncated error messages ("it says something about authentication") are nearly impossible to debug.

4. Debug output:

gemini --debug "your minimal prompt" 2>&1 | tee bug-report.txt
# Attach bug-report.txt to your GitHub issue

5. What you expected vs. what actually happened. These should be two separate, specific statements. "It doesn't work" is not a useful description of expected behaviour.

6. Steps to reproduce. Number them. Assume the reader has a fresh machine with nothing installed.

The Gemini CLI GitHub repository is at github.com/google-gemini/gemini-cli. Check open issues before filing — your bug may already be reported and acknowledged.

---

FAQ

Q: Gemini CLI worked yesterday but stops working today. What changed?

Most commonly: your API key was regenerated or deleted, your quota rolled over and you hit a lower soft limit, or the CLI auto-updated to a new version that introduced a breaking change. Check each of these in order: run the curl diagnostic to confirm the key is valid, check your quota dashboard, and if you suspect a version issue, pin to the previous version with npm install -g @google/gemini-cli@<previous-version>.

Q: The CLI runs but produces empty or truncated output for large inputs.

This is almost always a token limit issue, not a bug. The model has a maximum output token limit per request. For large summarisation or analysis tasks, split the input into chunks and process each chunk separately, then synthesise the results. You can also explicitly ask the model to "continue from where you left off" in a follow-up message.

Q: Can I use Gemini CLI behind a corporate proxy that does HTTPS inspection?

Yes, but you need to configure Node.js to trust the corporate CA certificate. Set NODE_EXTRA_CA_CERTS to the path of your corporate root certificate in PEM format. Your IT department can provide this file. Without it, every HTTPS request will fail with a certificate validation error.

Q: How do I run multiple Gemini CLI commands in parallel without hitting rate limits?

The safest approach is to use a semaphore-based concurrency limiter in your shell scripts. Limit parallel requests to two or three maximum, and build in a small delay between batches. Tools like GNU Parallel have built-in rate limiting flags (--delay) that work well for this use case. When in doubt, serialize your requests — the time saved by parallelism is often lost to retrying 429 errors.

Q: The --debug flag shows that requests are succeeding (200 OK), but the response content is wrong or unhelpful. Is this a bug?

Usually not. A 200 response with unhelpful content is a prompting problem, not a bug. The model is working correctly — it is just not receiving the context or instructions it needs to give you a useful answer. Review your GEMINI.md context file, ensure you are providing enough context in the prompt, and consider whether the task is within the model's capabilities. If the output is consistently wrong in a way that seems systematic (e.g., the model always ignores a specific instruction), that may be worth reporting.

---

Conclusion

Troubleshooting Gemini CLI effectively comes down to methodical elimination. The failure surface is wide — your API key, your network, your configuration, your Node.js environment, the remote service itself — but each layer can be tested independently, and most issues reveal themselves quickly once you know which diagnostic commands to run.

The single most important habit is using the --debug flag as soon as something behaves unexpectedly. The raw HTTP traffic tells you more in ten seconds than five minutes of guessing. Combined with the curl-based API key check (which bypasses the CLI entirely), you can immediately narrow down whether a problem is local or remote, authentication or network, configuration or code.

For persistent or unusual issues, the Gemini CLI GitHub repository is active and responsive. The quality of your bug report determines the quality of the fix — a minimal reproducer and full debug output are the two things that make the difference between a closed issue and an open one.

Keep this handbook bookmarked. The specific error messages change between versions, but the diagnostic approach remains the same: start at the checklist, follow the evidence, and fix the narrowest possible scope.

---

Found an error in this guide or have a troubleshooting scenario not covered here? The comments are open.