Debug Common Issues
Troubleshoot and resolve common problems you might encounter while using Gemini CLI.
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.
# Check if API key is set
echo $GOOGLE_AI_API_KEY
# Set API key (replace with your key)
export GOOGLE_AI_API_KEY="your-api-key-here"
# Make it permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GOOGLE_AI_API_KEY="your-api-key-here"' >> ~/.bashrc
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.
# 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.
# 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.
# 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: