Troubleshooting Guide

Support

Common issues and step-by-step solutions for Gemini CLI. Find quick fixes for installation, authentication, and runtime problems.

Quick Help

Check Installation

gemini --version

Test Authentication

gemini /about

Enable Debug Mode

gemini --verbose

Installation & Updates

Command not found: gemini

Common causes: CLI not installed globally, PATH not updated, Running from source incorrectly

Solutions:

Install globally via npm

npm install -g @google/gemini-cli@latest

If running from source

node packages/cli/dist/index.js

Verify installation

gemini --version

MODULE_NOT_FOUND or import errors

Common causes: Dependencies not installed, Project not built, Version mismatch

Solutions:

Install dependencies

npm install

Build the project

npm run build

Run preflight checks

npm run preflight

Authentication

API key authentication failed

Common causes: Invalid API key, Incorrect environment variable, Key has spaces/quotes

Solutions:

Verify API key format

echo $GEMINI_API_KEY

Set API key correctly

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

Make permanent (bash)

echo 'export GEMINI_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

Vertex AI authentication issues

Common causes: Not logged in to gcloud, Missing project permissions, Wrong environment variables

Solutions:

Login to gcloud

gcloud auth application-default login

Set required variables

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI=true

Verify permissions

gcloud projects describe $GOOGLE_CLOUD_PROJECT

Runtime & Performance

Slow responses or timeouts

Common causes: Network issues, Large file processing, Heavy tool usage

Solutions:

Enable verbose mode

gemini --verbose

Check network connectivity

ping api.google.com

Reduce file size with filtering

# Configure in settings.json
{
  "fileFiltering": {
    "respectGitIgnore": true
  }
}

High memory usage or crashes

Common causes: Processing large files, Memory leaks, Insufficient system resources

Solutions:

Check memory usage

gemini --show_memory_usage

Use file filtering

# Add to .gitignore to exclude large files
node_modules/
dist/
*.log

Restart CLI session

exit
gemini

Sandboxing

Sandbox failed to start

Common causes: Docker not running, Insufficient permissions, Missing sandbox image

Solutions:

Check Docker status

docker --version
docker info

Enable debug mode

DEBUG=1 gemini -s -p "debug command"

Build sandbox image

BUILD_SANDBOX=1 gemini -s

Permission denied in sandbox

Common causes: File permissions, Volume mount issues, SELinux/AppArmor restrictions

Solutions:

Check file permissions

ls -la /path/to/your/files

Verify sandbox environment

gemini -s -p "run shell command: env | grep SANDBOX"

Check mount points

gemini -s -p "run shell command: mount | grep workspace"

Tools & MCP

MCP server connection failed

Common causes: Server not running, Wrong configuration, Network issues

Solutions:

Check MCP status

/mcp

Verify server configuration

# Check settings.json
{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server"
    }
  }
}

Test server manually

node mcp_server.js --test

Tools not appearing

Common causes: Tool discovery failed, Path issues, Permission problems

Solutions:

List available tools

/tools desc

Check tool discovery command

# In settings.json
{
  "toolDiscoveryCommand": "bin/get_tools"
}

Verify tool permissions

ls -la bin/get_tools

Debugging Tips

Enable Verbose Logging

Get detailed output for troubleshooting

gemini-cli-command --verbose

Check Version Information

Verify installation and get version details

gemini --version
gemini /about

View Token Usage

Monitor API usage and costs

/stats

Debug Node.js Issues

Use Node.js inspector for development

node --inspect packages/cli/dist/index.js

Still Need Help?

File a Bug Report

Use the built-in bug reporting command or visit GitHub directly

/bug Your issue description here

Check Community Resources

Collecting Debug Information

When reporting issues, include this information to help with diagnosis

System Information

# Gemini CLI version
gemini --version

# Node.js version
node --version

# npm version
npm --version

# Operating system
uname -a  # On macOS/Linux
systeminfo | findstr /C:"OS"  # On Windows

Configuration Check

# Check environment variables
echo $GEMINI_API_KEY | head -c 10  # First 10 chars only
echo $GOOGLE_CLOUD_PROJECT
echo $GEMINI_SANDBOX

# Check settings location
ls -la ~/.gemini/settings.json
ls -la .gemini/settings.json

Explore Related Resources

Configuration Guide Command Reference Community Support