Troubleshooting Guide
Solutions to common problems and frequently asked questions about Gemini CLI. Find quick fixes and detailed guidance for various issues.
Quick Diagnostic Commands
Start with these commands to diagnose common issues
gemini --versionCheck CLI version and build information
gemini config listDisplay current configuration settings
gemini config resetReset configuration to default values
gemini logsView recent error logs and debug information
gemini doctorRun diagnostic checks and health verification
gemini cache clearClear cached data and temporary files
Common Issues & Solutions
Browse by category to find solutions to specific problems
Installation Issues
Problems during installation and setup
npm install fails with permission errors
Use npm with --global flag or configure npm to use a different directory. On macOS/Linux, you may need to use sudo or configure npm properly.
Solution:
npm install -g @google/generative-ai-cliCommand not found after installation
Ensure npm global bin directory is in your PATH. Check with `npm config get prefix` and add the bin directory to your PATH.
Solution:
export PATH=$PATH:$(npm config get prefix)/binNode.js version compatibility issues
Gemini CLI requires Node.js 16 or higher. Update Node.js using nvm or download from nodejs.org.
Solution:
node --version # Should be 16.0.0 or higherAuthentication & API Issues
Problems with API keys and authentication
Invalid API key error
Verify your API key is correct and has proper permissions. Get a new key from Google AI Studio if needed.
Solution:
gemini config set api-key YOUR_API_KEYAPI quota exceeded
Check your usage limits in Google AI Studio. Consider upgrading your plan or implementing rate limiting.
Solution:
gemini config set rate-limit 10 # Requests per minuteNetwork connectivity issues
Check internet connection and firewall settings. Verify proxy configuration if behind corporate firewall.
Solution:
gemini config set proxy http://proxy.company.com:8080Configuration Problems
Issues with CLI configuration and settings
Configuration file corrupted or missing
Reset configuration to defaults and reconfigure. Backup important settings first.
Solution:
gemini config reset
gemini config set api-key YOUR_API_KEYModel not available or deprecated
Check available models and update configuration. Some models may have regional restrictions.
Solution:
gemini models list
gemini config set model gemini-proEnvironment variables not recognized
Ensure environment variables are properly set and exported. Check variable names and values.
Solution:
export GEMINI_API_KEY=your_key_here
export GEMINI_MODEL=gemini-proPerformance Issues
Slow responses and performance problems
Slow response times
Check network connection, reduce request size, or try a different model. Consider using streaming for long responses.
Solution:
gemini config set stream true
gemini config set max-tokens 1000High memory usage
Limit conversation history, reduce batch sizes, or restart the CLI session periodically.
Solution:
gemini config set history-limit 10
gemini session clearTimeout errors
Increase timeout settings or break large requests into smaller chunks.
Solution:
gemini config set timeout 60000 # 60 secondsTool & Plugin Issues
Problems with tools and plugin functionality
Tool execution fails
Check tool permissions, file paths, and dependencies. Verify tool is properly installed and configured.
Solution:
gemini tools list
gemini tools test tool-namePlugin not loading
Verify plugin path, check for syntax errors, and ensure all dependencies are installed.
Solution:
gemini plugins list
gemini plugins reload plugin-nameMCP server connection issues
Check server status, network connectivity, and protocol version compatibility.
Solution:
gemini mcp status
gemini mcp reconnect server-nameStill Need Help?
If you can't find a solution here, try these resources