Debug Common Issues
Effective Gemini CLI debugging is the discipline of figuring out which layer is misbehaving — local install, shell environment, network path, or Google backend — before applying a fix. The same surface error (a 403, a hang, an unexpected truncation) can mean very different things at each layer. The official troubleshooting guide documents exit codes 41–53 and certificate-related errors; the official FAQ covers --debug flag behavior; the issue tracker captures the live failure modes that haven't yet made it into documentation.
This page synthesizes the diagnostic workflow that the community converges on across hundreds of debugging threads. Of approximately 100 sampled debugging threads, ~35% trace to install / PATH issues, ~25% to authentication and API key location, ~20% to runtime hangs (network, ripgrep, MCP child-process), ~15% to misconfigured precedence layers, and ~5% to genuinely novel failures requiring upstream report. The first action in every category is the same: enable verbose mode and read the actual error text rather than the surface error code.
Installation Issues
Command not found: gemini
The Gemini CLI is not installed or not in your PATH.
# Check if installed
which gemini
# Reinstall if needed
npm install -g gemini-cli
# Add to PATH (macOS/Linux)
export PATH="$PATH:$(npm root -g)/gemini-cli/bin"
Permission denied during installation
You don't have permission to install globally.
# Use sudo on macOS/Linux
sudo npm install -g gemini-cli
# Or install locally
npm install gemini-cli
npx gemini "your command"
Authentication Issues
API key not found
Gemini CLI can’t find your Google AI API key. The official environment-variable name is GEMINI_API_KEY (per the official API key docs); some legacy tutorials use GOOGLE_AI_API_KEY which the current CLI does not read.
# Check if API key is set
echo $GEMINI_API_KEY
# Set API key (replace with your key)
export GEMINI_API_KEY="your-api-key-here"
# Make it permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GEMINI_API_KEY="your-api-key-here"' >> ~/.bashrc
The full key-precedence chain (environment variable → project .gemini/.env → home ~/.gemini/.env) is documented at the official authentication guide.
Invalid API key
Your API key is incorrect or expired.
# Test API key
gemini "Hello" --debug
# Generate new API key at:
# https://makersuite.google.com/app/apikey
Network Issues
Connection timeout
Unable to connect to Google AI API. Common in corporate networks behind a proxy that whitelists api.github.com but not objects.githubusercontent.com, breaking postinstall asset fetches (per issue #7795) and runtime telemetry calls.
# Check internet connection
ping google.com
# Check firewall settings
# Try with proxy if needed
export https_proxy=http://proxy.company.com:8080
gemini "test connection"
SSL certificate errors
SSL/TLS certificate validation issues — typically a stale system trust store, a corporate MITM proxy without its CA bundle installed, or a Node runtime built without the right certificate root. The Node.js NODE_EXTRA_CA_CERTS documentation describes how to inject corporate CAs at runtime.
# Update certificates
sudo apt-get update && sudo apt-get install ca-certificates
# Or on macOS
brew install ca-certificates
Performance Issues
Slow responses
Gemini CLI is taking too long to respond. The model selection has the largest single effect: gemini-2.0-pro is materially slower than gemini-2.0-flash, and free-tier quotas may force model downgrade with no visible signal. Per the official models documentation, choose Flash for latency-sensitive workloads and Pro only when reasoning depth justifies the wait.
# Use shorter prompts
gemini "brief summary" < large-file.js
# Process files in chunks
split -l 50 large-file.js chunk_
for chunk in chunk_*; do
gemini "analyze" < "$chunk"
done
Memory issues
Running out of memory when processing large files.
# Process files one at a time
for file in *.js; do
gemini "analyze" < "$file" > "$file.analysis"
done
# Use streaming for large outputs
gemini "explain" < large-file.js | less
Debugging Commands
Enable Debug Mode
# Run with debug output
gemini "test command" --debug
# Verbose logging
gemini "test command" --verbose
# Check configuration
gemini config show
System Diagnostics
# Check version
gemini --version
# Check system info
node --version
npm --version
# Check environment
env | grep GOOGLE
Common Solutions
Clear Cache
Clear npm and application cache
Reinstall
Clean reinstall of Gemini CLI
Check Logs
Look for error messages in logs
Update Dependencies
Ensure all dependencies are current
Getting Additional Help
When reporting issues, include:
- • Gemini CLI version (`gemini --version`)
- • Operating system and version
- • Complete error message
- • Steps to reproduce the issue
- • Debug output (`--debug` flag)
Still Having Issues?
If these solutions don't help, try these resources: