Troubleshooting

Common issues and their solutions. Click any issue below to see the detailed solution.

Installation Issues

"Command not found: gemini"

Click to see solution →

The Gemini CLI is not installed or not in your PATH

Windows NPX Installation Issues

Click to see solution →

Error: unknown option "-y" when using Claude Code on Windows

"MCP server not responding"

Click to see solution →

Claude Desktop can't connect to the MCP server

Connection Issues

"Failed to connect to Gemini"

Click to see solution →

API connection issues or authentication problems

"Timeout errors"

Click to see solution →

Requests taking too long or timing out

"MCP error -32000: Connection closed"

Click to see solution →

Server fails to start and connection closes immediately (Claude Code)

"Gemini gets cut off" / Early Termination

Problem: Responses appear truncated or Claude reports "Gemini was thinking but got cut off"

Causes:

• Large codebase analysis taking longer than expected
• Complex operations requiring extended processing time
• Client connection management issues

Solutions:

# The tool automatically prevents timeouts with progress updates
# You'll see messages like:
# "🔍 Starting analysis (may take 5-15 minutes for large codebases)"
# "🧠 Gemini is analyzing your request..."

# Use faster Flash model for large requests
/gemini-cli:analyze -m gemini-2.5-flash @large-file.js

# Break up large analysis into smaller chunks
/gemini-cli:analyze @specific-function.js explain this function

File Analysis Issues

"File not found"

• Use absolute paths when possible
• Check file permissions
• Verify working directory

"Token limit exceeded" / "Response exceeds maximum allowed tokens (25000)"

Problem: Error shows response of 45,735 tokens even for small prompts

Root cause: Model-specific bug in gemini-2.5-pro (default model)

Working models:

• ✅ gemini-2.5-flash - Works perfectly
• ❌ gemini-2.5-pro - Always returns 45k+ tokens
• ❌ gemini-2.0-flash-thinking - Model not found

Solutions:

# Use Flash model (recommended)
/gemini-cli:analyze -m gemini-2.5-flash "your prompt"

# For large contexts, break into smaller chunks
/gemini-cli:analyze -m gemini-2.5-flash @file1.js @file2.js

# Alternative: Use Pro for larger contexts when it works
/gemini-cli:analyze -m gemini-2.5-pro "brief analysis only"

Configuration Issues

Changes not taking effect

1. Save config file
2. Completely quit Claude Desktop
3. Restart Claude Desktop
4. Verify with /gemini-cli:help

Environment variables not working

# Check current settings
echo $GEMINI_MODEL
echo $GOOGLE_GENERATIVE_AI_API_KEY

Configurable Timeout for Large Codebases

Problem: Default MCP client timeout too short for large analysis

Root Cause: Claude Desktop/Claude Code has a hard-coded timeout that cannot be overridden by environment variables.

Solution: The tool now automatically sends progress updates to prevent timeouts

# The tool will automatically send progress messages like:
# "🔍 Starting analysis (may take 5-15 minutes for large codebases)"
# "🧠 Gemini is analyzing your request..."
# "📊 Processing files and generating insights..."
# "⏳ Still processing... Gemini is working on your request"

What happens during long operations:

• Progress updates every 25 seconds during active processing
• Backup heartbeat every 20 seconds to ensure connection stays alive
• Clear status messages showing the tool is working
• Automatic completion notification when done

For very large codebases (10,000+ files):

• Consider breaking analysis into smaller chunks
• Use more specific file patterns with @ syntax
• Switch to gemini-2.5-flash for faster processing

## Debug Mode

Enable debug logging:
```json
{
  "mcpServers": {
    "gemini-cli": {
      "command": "gemini-mcp",
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Getting Help

1. Check GitHub Issues
2. Enable debug mode
3. Collect error logs
4. Open a new issue with details

Model-Specific Issues

Gemini-2.5-Pro Issues

Known problems:

• Always returns 45,735 token responses (bug)
• May cause "response exceeds limit" errors
• Not recommended for file analysis

Workaround: Use Gemini Flash instead

/gemini-cli:analyze -m gemini-2.5-flash "your prompt"

Model Recommendations

Use Case	Recommended Model	Reason
File analysis	gemini-2.5-flash	Faster, stable responses
Code review	gemini-2.5-flash	Good balance of speed/quality
Large codebase	gemini-2.5-flash	Better timeout handling
Quick questions	gemini-2.5-flash	Fast responses

Quick Fixes

Reset Everything

# Remove and reinstall
npm uninstall -g gemini-mcp-tool
npm install -g gemini-mcp-tool

# Reset Gemini CLI
gemini config reset
gemini config set api_key YOUR_API_KEY

Test Basic Functionality

# Test Gemini CLI
gemini "Hello"

# Test MCP Tool with Flash model
/gemini-cli:ping

# Test file analysis with working model
/gemini-cli:analyze -m gemini-2.5-flash @README.md summarize

Platform-Specific Issues

Windows 11

• NPX flag issues: Use --yes instead of -y
• Path problems: Restart terminal after Node.js installation
• Connection issues: Ensure Windows Defender isn't blocking Node.js

macOS

• Permission issues: Use sudo if npm install fails
• Terminal restart: Required after installing dependencies

Linux

• Node.js version: Install via NodeSource for latest version
• npm permissions: Configure npm to avoid sudo usage