Title

Description

Title

Gemini CLI not found

Check installation and Node.js version

node --version && npm list -g @google/gemini-cli

Authentication failed

Check Google account or API key

echo $GEMINI_API_KEY | head -c 10

Permission denied

Check npm permissions or use npx

npx https://github.com/google-gemini/gemini-cli

Rate limit exceeded

Wait before making more requests

# Wait 60 seconds before retrying

Title

🔧

Installation Problems

Gemini CLI installation fails

Symptoms:
  • npm install errors
  • Permission denied
  • Node.js version issues
Solutions:
  1. 1Ensure Node.js 18+ is installed: node --version
  2. 2Use npx instead of global install: npx https://github.com/google-gemini/gemini-cli
  3. 3Clear npm cache: npm cache clean --force
Prevention:

Use the recommended npx method for running Gemini CLI

Command not found after installation

Symptoms:
  • gemini: command not found
  • PATH issues
  • Global install problems
Solutions:
  1. 1Use npx method: npx https://github.com/google-gemini/gemini-cli
  2. 2Check global npm directory: npm config get prefix
  3. 3Restart terminal and try again
Prevention:

Prefer npx over global installation for better compatibility

🔐

Authentication Issues

Google authentication fails

Symptoms:
  • Authentication failed
  • Browser not opening
  • OAuth errors
Solutions:
  1. 1Ensure you're using a personal Google account
  2. 2Clear browser cookies and try again
  3. 3Use API key method: export GEMINI_API_KEY='your_key'
Prevention:

Use API key authentication for automated workflows

API key not working

Symptoms:
  • Invalid API key
  • 401 Unauthorized
  • Authentication errors
Solutions:
  1. 1Verify API key from https://aistudio.google.com/apikey
  2. 2Check environment variable: echo $GEMINI_API_KEY
  3. 3Regenerate API key if needed
Prevention:

Store API keys securely and rotate them regularly

Diagnostic Tools

System Check

node --versionCheck Node.js version (need 18+)
npm --versionVerify npm installation
npm list -g @google/gemini-cliCheck Gemini CLI installation
echo $GEMINI_API_KEYCheck API key environment variable
curl -I https://generativelanguage.googleapis.comTest API connectivity

Debug Mode

DEBUG=* npx https://github.com/google-gemini/gemini-cli

Enable debug mode to see detailed logs and connection information

Debug techniques:

  • DEBUG=* - Enable all debug logs
  • --verbose - Verbose output (if supported)
  • console.log - Check browser console for errors

Getting Help

📚

Documentation

Check official documentation and guides

Browse Docs
💬

Community Forum

Ask questions and share solutions with the community

Join Discussion
🐛

Issue Tracker

Report bugs and request new features

Report Issue