Gemini CLI Won't Start or Authenticate? Where to Look First

npm install fails. The auth window never opens. The gemini command you just installed is not found. Most trouble with the Gemini CLI clusters in the setup phase, before you ever run a real prompt.

What follows is organised by area — installation, authentication, PATH, sandboxing, proxies, and rate limits — pairing the error text you will actually see with the fix for it.

Installation Issues

Node.js Version Doesn't Meet Requirements

Gemini CLI requires Node.js 18.0.0 or higher. If you're using an older version, you'll get compatibility errors during installation.

# Check your current Node.js version
node --version
 
# Upgrade Node.js (macOS with Homebrew)
brew upgrade node
 
# Or install the latest version
brew install node

After upgrading, clear the npm cache and reinstall:

npm cache clean --force
npm install -g @google/generative-ai-cli

npm Permission Denied Error

When installing global npm packages, you might see permission errors because npm lacks write access to system directories.

Recommended solution: Configure npm to use a user directory instead of sudo.

# Check npm's current prefix
npm config get prefix
 
# Create and set a user-owned directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
 
# Add to PATH in ~/.bashrc or ~/.zshrc
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
 
# Now install without issues
npm install -g @google/generative-ai-cli

npm Install Fails with Network Errors

Unstable network connections can interrupt installation mid-process.

# Retry with increased timeout
npm install -g @google/generative-ai-cli --no-audit --legacy-peer-deps
 
# Or switch npm registry mirrors (useful in some regions)
npm config set registry https://registry.npmmirror.com
npm install -g @google/generative-ai-cli

Authentication Issues

API Key Not Recognized

Gemini CLI reads the API key from the GEMINI_API_KEY environment variable. If it's not set or the format is wrong, authentication fails.

# Check if the environment variable is set
echo $GEMINI_API_KEY
 
# If empty, set your API key
export GEMINI_API_KEY='YOUR_GEMINI_API_KEY'
 
# Make it permanent by adding to ~/.bashrc or ~/.zshrc
echo "export GEMINI_API_KEY='YOUR_GEMINI_API_KEY'" >> ~/.bashrc
source ~/.bashrc
 
# Verify the configuration
gemini auth test

Important: Generate your API key from Google AI Studio (https://aistudio.google.com). Never commit API keys to Git or include them in public repositories.

Google Account Authentication Fails

Some operations require communication with Google's servers. If you're behind a proxy, authentication might fail.

# Clear cached credentials
gemini auth clear
 
# Log in again
gemini auth login
 
# If behind a proxy, configure proxy settings
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=https://proxy.example.com:8080
gemini auth login

Command Not Found Error

PATH Configuration Is Incorrect

The "gemini: command not found" error means the installed command isn't in your system's PATH.

# Check where npm installs global packages
npm config get prefix
 
# Verify PATH includes the installation directory
echo $PATH
 
# If not included, add to ~/.bashrc or ~/.zshrc
export PATH="/usr/local/bin:$PATH"
# Or if npm uses a custom directory:
export PATH="$HOME/.npm-global/bin:$PATH"
 
# Apply changes immediately
source ~/.bashrc

Shell Configuration File Not Applied

On newer macOS versions, zsh is the default shell. Adding settings to bash won't work.

# Check your current shell
echo $SHELL
 
# If using zsh, add to ~/.zshrc instead
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
 
# Open a fresh terminal window to verify
gemini --version

Plan Mode Unavailable

Plan Mode requires a Pro plan subscription in Google AI Studio. Without it, you'll get errors when trying to use Plan Mode.

# Check your account status
gemini status
 
# Verify Pro plan enrollment at:
# https://aistudio.google.com/app/plan

After subscribing to Pro, clear cached credentials and log in again:

gemini auth clear
gemini auth login

For detailed Plan Mode usage, see "[Gemini CLI Plan Mode Guide]((/articles/gemini-dev/gemini-cli-plan-mode)".

Linux-Specific Issues (gVisor Sandbox)

On Linux, gVisor sandbox-related errors may appear, especially when running Plan Mode.

# Check if gVisor is installed (Ubuntu/Debian)
which runsc
 
# If missing, you'll see:
# E: Cannot locate runsc
 
# Install gVisor (Ubuntu 20.04+)
curl -fsSL https://gvisor.dev/archive.key | sudo apt-key add -
sudo add-apt-repository "deb https://storage.googleapis.com/gvisor/releases release main"
sudo apt-get update
sudo apt-get install -y runsc

To skip sandbox requirements, set this environment variable:

export GEMINI_CLI_NO_SANDBOX=1
gemini plan

Network and Proxy Errors

Connection Timeout

Network delays or proxy issues can cause connection timeouts.

# Increase timeout value
export NODE_OPTIONS="--max-old-space-size=4096"
gemini --timeout 60000 plan
 
# Configure proxy settings
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
gemini plan

SSL/TLS Certificate Error

Corporate SSL inspection proxies can cause certificate validation failures.

# Allow self-signed certificates (development only)
export NODE_TLS_REJECT_UNAUTHORIZED=0
gemini plan
 
# Better approach: Add corporate CA to system
# Linux
sudo cp /path/to/ca-certificate.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
 
# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/ca-certificate.crt

Rate Limit Error (429 Too Many Requests)

A 429 error means you've exceeded your API key's request limit within a time period.

# Check your usage and limits
gemini status
 
# Set retry delay (in milliseconds)
export GEMINI_RETRY_DELAY=5000  # Wait 5 seconds between retries
gemini plan

For more details on rate limiting, see "[Gemini API 429 Error and Quota Troubleshooting]((/articles/gemini-api/gemini-api-quota-429-error-troubleshooting)".

Version Upgrade Troubleshooting

Changes Between v0.34.0 and v0.35.0

Version 0.35.0 modified some configuration file formats. Old config files can cause errors with the new version.

# Check your installed version
gemini --version
 
# Upgrade to the latest
npm install -g @google/generative-ai-cli@latest
 
# Reset configuration
gemini config reset
 
# Clear cache
gemini cache clear

After upgrading, reconfigure your settings:

gemini auth login
gemini config set model gemini-2.5-pro

Setup Verification Script

Use this script to diagnose your entire Gemini CLI setup at once:

#!/bin/bash
# Gemini CLI Setup Diagnostic Script
 
echo "=== Gemini CLI Setup Diagnostic ==="
 
# Check Node.js version
echo -n "Node.js: "
node --version
 
# Check npm version
echo -n "npm: "
npm --version
 
# Check Gemini CLI installation
echo -n "Gemini CLI: "
if command -v gemini &> /dev/null; then
  gemini --version
else
  echo "Not installed"
  exit 1
fi
 
# Check API key configuration
if [ -z "$GEMINI_API_KEY" ]; then
  echo "Warning: GEMINI_API_KEY environment variable not set"
else
  echo "API Key: Configured (first 10 chars: ${GEMINI_API_KEY:0:10}...)"
fi
 
# Verify PATH
echo -n "gemini in PATH: "
which gemini
 
# Run functionality tests
echo "--- Feature Tests ---"
gemini auth test && echo "Authentication: OK" || echo "Authentication: FAILED"

Run this script to quickly identify which component needs attention.

Next Steps

Once your setup is complete, explore these guides:

[Gemini CLI Complete Guide]((/articles/gemini-dev/gemini-cli-guide) — In-depth command reference and configuration options
[Gemini CLI Plan Mode Guide]((/articles/gemini-dev/gemini-cli-plan-mode) — Advanced planning features

Resources

If your issue persists, reach out to the Google AI Studio community forums for support.