Troubleshooting Guide

This guide provides solutions to common technical issues, error messages, and configuration problems you might encounter while using Cursor, Claude Code, and MCP servers.

Tip

Quick tip: Use Ctrl/Cmd + F to search for your specific error message or issue.

Cursor Issues

Installation & Setup Problems

Cursor won’t start after installation

1. Check system requirements

   • macOS 10.15+, Windows 10+, or Linux (64-bit)
   • At least 4GB RAM (8GB recommended)
   • 2GB free disk space

2. Try safe mode

   cursor --disable-extensions

3. Reset user data (backup first!)

   • Windows: %APPDATA%\Cursor
   • macOS: ~/Library/Application Support/Cursor
   • Linux: ~/.config/Cursor

4. Check for conflicting software

   • Antivirus blocking execution
   • Corporate proxy settings
   • Firewall rules

Can’t import VS Code settings

Solution: Ensure VS Code is closed during import. If that fails:

1. Export VS Code settings manually: Code > Preferences > Profiles > Export
2. Import in Cursor: File > Preferences > Profiles > Import

AI Feature Issues

Tab autocomplete not working

Check Plan Limits

Free tier: 2,000 completions/month Pro tier: Unlimited View usage in Settings → Subscription

Verify Indexing

Settings → Features → Codebase Indexing Should show “Indexed” status Click “Reindex” if needed

Model Status

Check status.cursor.sh Tab model might be experiencing issues Try switching to backup model

File Support

Some file types have limited support Check if your language is supported Try in a standard .js/.py file

Agent mode can’t modify files

Common causes and solutions:

1. Wrong mode selected

   • Ensure “Agent” is selected, not “Chat”
   • Agent mode shows pencil icon

2. File permissions

   # Check file permissions
   ls -la filename
   # Fix if needed
   chmod 644 filename

3. Git locks

   # Remove git index lock
   rm .git/index.lock

4. Read-only files

   • Check file isn’t marked read-only
   • Verify you have write access to directory

”Context window exceeded” error

Quick Fix

1. Reduce @-mentioned files
2. Use specific line ranges: @file.js:10-50
3. Clear chat and start fresh

Advanced Solutions

// Instead of including entire file
@large-file.ts

// Include specific sections
@large-file.ts:100-200  // Just the relevant function
@large-file.ts:exported  // Just exports
@large-file.ts:UserClass // Just a specific class

Enable Max Mode for 200k context (costs more):

• Click model dropdown → Enable Max Mode

Getting “Rate limit exceeded”

Your fast requests are exhausted. Options:

1. Wait for slow requests (unlimited but delayed)
2. Upgrade plan for more fast requests
3. Use your API key for unlimited (pay per use)
4. Check usage: Settings → Subscription → Usage

Performance Issues

Cursor is running slowly

1. Disable unused extensions

   • View → Extensions
   • Disable non-essential ones

2. Reduce indexing scope

   .cursorignore

   node_modules/
   dist/
   *.log
   coverage/

3. Clear cache

   • Cmd/Ctrl + Shift + P → “Clear Editor History”
   • Restart Cursor

4. Check system resources

   • Close other heavy applications
   • Ensure adequate RAM available

High memory usage

Common with large codebases. Solutions:

• Exclude large directories from indexing
• Use .cursorignore aggressively
• Consider splitting monorepo workspaces
• Close unused editor tabs and windows

What If AI Models Keep Making Basic Mistakes?

It's Almost Never the Model's Fault

When Sonnet 4, Opus 4.1, or GPT-5 consistently produce poor results, the issue is typically in your configuration or usage patterns - not the model itself. These are state-of-the-art systems that excel when properly configured.

Quick Diagnostic Guide

Follow this checklist to identify and fix common AI performance issues:

❌ Model Doesn't Understand Your App

Symptom: AI suggests patterns that don’t match your codebase

Fix for Cursor:

• Run /Generate Cursor Rules command in Cursor
• Update weekly as codebase evolves

Fix for Claude Code:

> /init
# Updates CLAUDE.md with current context

❌ AI Reimplements Existing Features

Symptom: Creates duplicate functionality

Solution: Use explicit file references

@auth.ts extend the existing login
@components/Modal.tsx use this pattern
@api/* follow these conventions

❌ Consistently Poor Responses

Symptom: Low-quality or incorrect suggestions

Check:

• Model: Using Sonnet 4, Opus 4.1, or GPT-5?
• Mode: MAX mode enabled for complex tasks?
• Context: “Include entire codebase” checked?

❌ AI Forgets Important Details

Symptom: Loses track of requirements mid-task

Cursor Solution: Enable MAX mode

Cmd/Ctrl + Shift + P → Toggle MAX Mode

Claude Code Solution:

> ultrathink about this complex problem

❌ Library/Framework Confusion

Symptom: Wrong API usage or outdated patterns

Solution: Use Context7 MCP or web search

# Option 1: Install Context7 MCP
claude mcp install @context7/context7-mcp
# In prompts: "Use Context7 MCP for React documentation"

# Option 2: Use web search (no setup needed)
# In prompts: "Search the web for React hooks documentation"

❌ Unexpected Implementations

Symptom: AI takes wrong approach

Solution: End prompts with clarification request

"Build user authentication...
Ask me about everything you need to
implement this in the best way possible."

The Success Formula

1. Initialize Proper Context

   • Cursor: Run /Generate Cursor Rules and maintain regularly
   • Claude Code: Run /init and update CLAUDE.md regularly

2. Use Maximum Model Capabilities

   • Enable MAX mode for tasks over 5 minutes
   • Use ultrathink for architectural decisions
   • Select Opus 4.1 for complex logic

3. Provide Explicit References

   • Use @-mentions for files and folders
   • Include examples of desired patterns
   • Reference existing implementations

4. Request Clarification

   • End prompts asking what AI needs
   • Use PRD→Plan→Todo workflow
   • Review plans before implementation

5. Configure Documentation Access

   • Option 1: Set up Context7 MCP server, use “Context7 for docs” in prompts
   • Option 2: Use web search: “Search the web for [library] documentation”
   • Keep documentation sources updated

Still Having Issues?

If you’ve followed all these steps and still experience problems:

1. Verify API Status: Check status.cursor.sh or status.anthropic.com
2. Update Software: Ensure you’re on the latest version
3. Check Rate Limits: You might be hitting usage limits
4. Report Bugs: Use official support channels with specific examples

Remember: These models are incredibly powerful when configured correctly. Investment in proper setup pays dividends in productivity.

Claude Code Issues

Installation Problems

Command not found: claude

npm

# Reinstall globally
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# Check installation
npm list -g @anthropic-ai/claude-code

Path Issues

# Add npm global to PATH
export PATH="$PATH:$(npm config get prefix)/bin"

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc

Windows: “Git not found” error

Claude Code requires Git for Windows:

1. Download from git-scm.com
2. Install with “Add to PATH” option
3. Restart terminal
4. Verify: git --version

Authentication Issues

API key not working

1. Verify key format

   • Should start with sk-ant-
   • No extra spaces or quotes

2. Check key permissions

   • Log into console.anthropic.com
   • Verify key is active
   • Check usage limits

3. Set correctly

   # Option 1: Environment variable
   export CLAUDE_API_KEY="sk-ant-..."
   
   # Option 2: During setup
   claude login

4. Test connection

   claude "hello"

SSO login failing

For enterprise SSO:

1. Ensure you’re on company network/VPN
2. Check with IT for firewall rules
3. Try: claude login --sso --verbose
4. Use fallback API key method if needed

Usage Limit Issues

”Rate limit reached” after few messages

Understanding limits:

• Pro: ~45 messages per 5-hour window
• Max 5x: ~225 messages per 5-hour window
• Max 20x: ~900 messages per 5-hour window

Solutions:

1. Optimize usage

   # Clear between tasks
   /clear
   
   # Batch related questions
   claude "1. Fix bug X 2. Add feature Y 3. Write tests"

2. Check remaining quota

   /status

3. Use API for heavy workloads

   • Pay per token instead of message limits
   • No time-based restrictions

Execution Problems

Permission denied errors

Safe Approach

Configure allowed commands:

# Allow specific commands
claude config set allowed_commands "git,npm,ls"

# Allow file editing
claude config set auto_approve_file_edits true

Yolo Mode

Skip all permissions (use cautiously):

claude --dangerously-skip-permissions

Or in container for safety:

docker run -it claude-safe claude --dangerously-skip-permissions

Changes not being applied

1. Check working directory

   pwd  # Ensure you're in right location

2. Verify file paths

   • Claude uses paths relative to working directory
   • Check for typos in filenames

3. Git status

   git status  # See what changed
   git diff    # Review changes

MCP Server Issues

Connection Problems

MCP server won’t start

1. Check installation

   npm list -g @modelcontextprotocol/server-name

2. Verify configuration

   // ~/.claude/mcp.json or .mcp.json
   {
     "servers": {
       "github": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/github"]
       }
     }
   }

3. Debug mode

   claude --mcp-debug

4. Check logs

   • Look for error messages in output
   • Common: missing dependencies, auth issues

Authentication failures

GitHub MCP:

# Set PAT token
export GITHUB_TOKEN="ghp_..."

Database MCP:

# Check connection string
export DATABASE_URL="postgresql://user:pass@localhost:5432/db"

Performance Issues

MCP operations timing out

1. Increase timeout

   {
     "servers": {
       "slow-server": {
         "command": "...",
         "timeout": 30000  // 30 seconds
       }
     }
   }

2. Check server resources

   • Database might be overloaded
   • API rate limits
   • Network latency

Common Error Messages

Error: “Model is currently overloaded”

Meaning: The AI model servers are at capacity

Solutions:

1. Wait a few minutes and retry
2. Switch to a different model temporarily
3. Use during off-peak hours
4. Consider API usage for guaranteed availability

Error: “Invalid API key”

Check:

1. Key starts with correct prefix
2. No accidental spaces/characters
3. Key hasn’t been revoked
4. Using right key for right service

Error: “Context length exceeded”

Solutions:

1. Reduce input size
2. Use Max mode (Cursor)
3. Split into multiple requests
4. Remove unnecessary context

Error: “File not found”

Common causes:

1. Wrong working directory
2. Typo in filename
3. File deleted/moved
4. Case sensitivity (Linux/Mac)

Recovery Procedures

Corrupted chat history

1. Export current chat (if possible)

   • Cursor: Chat menu → Export
   • Claude Code: Copy terminal output

2. Clear problematic data

   • Cursor: Delete ~/.cursor/chats/
   • Claude Code: Start new session

3. Restore from export

   • Paste relevant context back

Lost code changes

Prevention:

# Always use git
git add -A && git commit -m "WIP: Before AI changes"

Recovery:

1. Check editor’s local history
2. Look for .swp or backup files
3. Use git reflog if committed
4. Check OS file recovery tools

Getting Help

Built-in diagnostics

Cursor:

• Help → Toggle Developer Tools
• Check Console for errors
• Copy and share with support

Claude Code:

/doctor  # Run diagnostics
/help    # Show available commands
claude --version  # Check version

Support channels

1. Documentation

   • docs.cursor.com
   • docs.anthropic.com

2. Community

   • Cursor Forum
   • Discord
   • Stack Overflow

3. Official Support

   • Enterprise: Priority support
   • Pro: Email support
   • Include diagnostics output

Caution

When reporting issues, always include:

• Tool version
• OS and version
• Steps to reproduce
• Error messages (full text)
• What you’ve already tried

Preventive Measures

Best practices to avoid issues

1. Regular updates

   # Cursor: Check for updates in-app
   # Claude Code:
   npm update -g @anthropic-ai/claude-code

2. Backup configurations

   # Backup Cursor settings
   cp -r ~/.cursor ~/.cursor.backup
   
   # Backup Claude Code config
   cp ~/.claude.json ~/.claude.json.backup

3. Monitor usage

   • Check quotas regularly
   • Set up usage alerts
   • Track costs for API usage

4. Use version control

   • Commit before major AI operations
   • Use branches for experiments
   • Tag stable versions

Remember: Most issues have simple solutions. Start with the basics (restart, update, check permissions) before trying complex fixes.