Troubleshooting
Having issues with Gemini CLI? Find solutions to common problems and get back to coding quickly.
Quick Diagnostic
Run this command to check your Gemini CLI installation and configuration:
gemini doctor
Installation Issues
npm install fails with permission errors
Try using npm with sudo or configure npm to use a different directory
sudo npm install -g @google/gemini-cli
Command not found after installation
Ensure npm bin directory is in your PATH
export PATH=$PATH:$(npm bin -g)
Version conflicts with existing packages
Clear npm cache and reinstall
npm cache clean --force && npm install -g @google/gemini-cli
Authentication Errors
Invalid API key error
Verify your API key is correct and has proper permissions
gemini config set api-key YOUR_VALID_API_KEY
API key not found
Ensure environment variable is set correctly
export GEMINI_API_KEY="your-api-key-here"
Authentication timeout
Check your network connection and firewall settings
curl -I https://generativelanguage.googleapis.com
Runtime Errors
Rate limit exceeded
Wait for the rate limit to reset or upgrade your API plan
# Check your current usage gemini usage --show-limits
Context length exceeded
Reduce the input size or split into smaller chunks
# Use --max-tokens to limit response gemini chat --max-tokens 1000
Unexpected response format
Update to the latest version of Gemini CLI
npm update -g @google/gemini-cli
Performance Issues
Slow response times
Check network latency and consider using a closer API endpoint
# Test network latency ping generativelanguage.googleapis.com
High memory usage
Limit concurrent operations and clear cache
gemini cache clear
Hanging or frozen commands
Use timeout flags and check for blocking operations
gemini chat --timeout 30
Enable Debug Mode
For more detailed error information, run Gemini CLI in debug mode:
# Enable debug logging
export GEMINI_DEBUG=true
# Or use the debug flag
gemini --debug [command]
Still having issues?
If you can't find a solution here, get help from the community or report a bug.