Troubleshooting Guide

Your AI agent just stopped mid-task, spat out an error you have never seen, or started generating code that has nothing to do with your project. Before you open a GitHub issue, run through this page. Most problems have a quick fix.

Tip

Use Ctrl/Cmd + F to search for your specific error message. Errors are listed verbatim where possible.

Cursor Issues

Installation and Setup

Cursor will not start after installation

1. Verify system requirements: macOS 10.15+, Windows 10+, or 64-bit Linux. At least 4GB RAM (8GB recommended), 2GB free disk space.

2. Try safe mode:

   cursor --disable-extensions

3. Reset user data (back up first):

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

4. Check for conflicts: Antivirus software, corporate proxies, and firewall rules can all block Cursor’s network access.

Cannot import VS Code settings

Close VS Code completely before importing. If automatic import fails:

1. In VS Code: File > Preferences > Profiles > Export
2. In Cursor: File > Preferences > Profiles > Import
3. Extensions, themes, keybindings, and settings all transfer

AI Feature Issues

Tab autocomplete not working

Check	Action
Plan limits	Free tier: 2,000/month. Check Settings > Subscription > Usage
Indexing status	Settings > Features > Codebase Indexing. Click “Reindex” if stale
Model status	Visit status.cursor.sh for outage reports
File type	Some file types have limited support. Test in a .js or .py file
Extensions	Disable competing completion extensions (Copilot, Tabnine)

Agent mode cannot modify files

1. Verify mode: The mode selector should show “Agent” (pencil icon), not “Ask”
2. File permissions: ls -la filename — ensure write access
3. Git locks: Remove stale locks with rm .git/index.lock
4. Read-only flag: Some editors or OS settings mark files as read-only

”Context window exceeded” error

Quick Fix

1. Remove @-mentioned files you do not strictly need
2. Use line ranges: @large-file.ts:100-200 instead of the whole file
3. Start a new chat with /clear context

Advanced

• Enable Max mode for the full 200K context window (costs more per request)
• Use Cmd/Ctrl+M to toggle between full-file and outline reading strategies
• Include specific symbols (@UserClass) instead of entire files

”Rate limit exceeded” — fast requests exhausted

Your monthly fast request quota is spent. Options:

1. Wait: Slow requests are unlimited but delayed
2. Upgrade: Pro+ ($60/month) or Ultra ($200/month) for more
3. Use your own API key: Settings > Models > API Keys (pay-per-use, no limits)
4. Check usage: Settings > Subscription > Usage for exact numbers

Performance Issues

Cursor running slowly

1. Disable unused extensions (View > Extensions)
2. Add a .cursorignore file:

   node_modules/
   dist/
   .git/
   *.log
   coverage/

3. Clear cache: Cmd/Ctrl+Shift+P > “Clear Editor History”
4. Close unused tabs and windows
5. Restart Cursor

High memory usage

Large codebases cause index bloat. Mitigations:

• Exclude large directories in .cursorignore
• Split monorepo workspaces into smaller Cursor windows
• Close editor tabs you are not actively using
• Disable features you do not use (e.g., semantic search for huge repos)

Claude Code Issues

Installation Problems

”Command not found: claude”

npm

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code
npm list -g @anthropic-ai/claude-code   # verify

PATH issues

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

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

Windows: “Git not found” error

Claude Code requires Git for Windows:

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

Authentication Issues

API key not working

1. Key should start with sk-ant- (no extra spaces or quotes)
2. Verify the key is active at console.anthropic.com
3. Set it correctly:

   export ANTHROPIC_API_KEY="sk-ant-..."

4. Test: claude "hello" — you should get a response
5. If using SSO: Use /login within the Claude Code REPL to re-authenticate

Usage Limits

”Rate limit reached” after a few messages

Understanding the limits:

Plan	Messages per 5-hour window
Pro ($20/month)	~10-40
Max 5x ($100/month)	~50-200
Max 20x ($200/month)	~200-800

Mitigation strategies:

1. Use /compact to summarize before the window fills up
2. Use /clear between unrelated tasks
3. Batch related questions: “1. Fix the auth bug 2. Add tests 3. Update the README”
4. Check remaining quota with /status
5. Consider API access for high-volume usage (pay per token, no window limits)

Execution Problems

Permission denied errors

Granular (recommended)

Configure specific permissions via /permissions or in .claude/settings.json. Pre-approve file editing, specific commands, or MCP tools.

Full trust (sandboxed only)

claude --dangerously-skip-permissions

Best combined with Docker for safety:

docker run -v $(pwd):/app -w /app claude-code \
  claude --dangerously-skip-permissions -p "fix all lint errors"

Changes not being applied

1. Verify you are in the correct directory: pwd
2. Check file paths — Claude uses paths relative to the working directory
3. Look for Git locks: rm .git/index.lock
4. Run git status and git diff to see what actually changed
5. If editing failed silently, try the operation again with a more explicit prompt

Codex Issues

Installation and Setup

Codex CLI not installing

npm install -g @openai/codex
codex --version

If permission errors occur:

sudo npm install -g @openai/codex    # macOS/Linux
# Or use nvm to manage Node without sudo

Authentication failing

1. Verify your OpenAI API key is set:

   export OPENAI_API_KEY="sk-..."

2. Check the key is active at platform.openai.com/api-keys
3. Ensure you have Codex access enabled on your plan
4. Test: codex "hello" — should respond without errors

Execution Problems

Worktree conflicts

Codex creates Git worktrees for each task. If a task fails mid-execution:

# List worktrees
git worktree list

# Remove stale worktrees
git worktree prune

# Force remove a specific worktree
git worktree remove /path/to/worktree --force

Sandbox command failures

Codex sandboxes command execution by default. If commands fail:

1. Check that the command is available in the sandbox environment
2. Verify network access settings — sandboxes may block outbound network by default
3. For commands needing network: configure sandbox to allow specific hosts
4. For local-only commands: ensure all dependencies are available in the worktree

Cloud agent not responding

1. Check your internet connection
2. Verify API key and plan status at platform.openai.com
3. Check Codex service status at status.openai.com
4. Try running the same task locally with codex CLI to isolate the issue
5. Cloud agents may queue during peak usage — check the task status in the App

MCP Server Issues

Connection Problems

MCP server will not start

1. Verify the package is installed:

   npx -y @modelcontextprotocol/server-github --help

2. Check configuration (Claude Code example):

   .mcp.json

   {
     "mcpServers": {
       "github": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-github"],
         "env": {
           "GITHUB_TOKEN": "ghp_..."
         }
       }
     }
   }

3. Debug mode:

   claude --debug    # shows MCP connection details

4. Check environment variables: Most MCP servers need tokens (GITHUB_TOKEN, DATABASE_URL, etc.)

MCP operations timing out

1. Increase timeout in configuration (default is usually 10-30 seconds)
2. Check if the external service (database, API) is responsive
3. Verify network connectivity from your machine
4. Some MCP servers have rate limits — check the server’s documentation

When the AI Keeps Making Basic Mistakes

Caution

When the model consistently produces poor results, the problem is almost always in your configuration or prompt strategy — not the model. These are the most capable coding models available. If they are failing, something in the setup is off.

Symptom	Root Cause	Fix
AI suggests patterns that do not match your codebase	Missing project context	Cursor: /Generate Cursor Rules. Claude Code: /init. Codex: update AGENTS.md
AI re-implements existing features	No reference to existing code	Use @ references to include relevant files. Be explicit: “extend the existing auth module”
Responses are generic or low-quality	Wrong model or mode	Verify you are using Opus 4.6 / GPT-5.3-Codex. Enable Max mode for complex tasks
AI forgets requirements mid-task	Context overflow	Use /compact to summarize. Break large tasks into smaller conversations
Wrong library APIs or outdated patterns	No documentation access	Install Context7 MCP or use @web to fetch current docs
AI takes a completely wrong approach	Insufficient direction	End prompts with “Ask me questions before you start implementing”

Common Error Messages

”Model is currently overloaded”

The AI provider’s servers are at capacity. Wait 1-2 minutes and retry. If persistent, switch to a different model temporarily or try during off-peak hours.

”Invalid API key”

1. Check that the key starts with the correct prefix (sk-ant- for Anthropic, sk- for OpenAI)
2. Ensure no extra whitespace or quotes
3. Verify the key has not been revoked at the provider’s dashboard
4. Confirm you are using the right key for the right service

”Context length exceeded”

The conversation plus file content exceeds the model’s context window. Reduce input: remove unnecessary files, use /compact, or split the task.

”File not found”

1. Wrong working directory (pwd to check)
2. Typo in filename
3. File deleted or moved
4. Case sensitivity (Linux and macOS file systems are case-sensitive by default)

Recovery Procedures

Lost code changes

Prevention (always do this before large AI operations):

git add -A && git commit -m "WIP: checkpoint before AI changes"

Recovery options:

1. Cursor checkpoints: Use the revert button in chat
2. Git reflog: git reflog shows every HEAD change, even uncommitted
3. Local history: Cursor/VS Code maintain a local file history per file
4. OS-level recovery: Time Machine (macOS), File History (Windows)

Corrupted chat history

1. Export the current chat if possible
2. Clear the problematic data:
   • Cursor: Delete ~/.cursor/chats/
   • Claude Code: Start a new session (old sessions remain accessible via claude -r)
3. Restart the tool

Built-in Diagnostics

Cursor

• Help > Toggle Developer Tools (check Console for errors)
• Cmd/Ctrl+Shift+P > “Cursor: Show Logs”
• Copy diagnostics output when reporting bugs

Claude Code

/doctor        # full health check
/status        # system and quota status
/help          # available commands
claude --version

Codex

codex --version
codex "What is my current configuration?"  # verify setup

Getting Help

Support Channels

Tool	Community	Official
Cursor	Forum, Discord	In-app feedback, enterprise support
Claude Code	Discord, GitHub Issues	support@anthropic.com, enterprise channels
Codex	Community, GitHub Issues	help.openai.com, enterprise support

Caution

When reporting issues, always include: tool version, OS and version, steps to reproduce, full error message text, and what you have already tried.

Preventive Measures

1. Update regularly: New releases often fix the exact bug you are experiencing
2. Back up configurations: Copy .cursor/, .claude/, and AGENTS.md before major updates
3. Monitor usage: Check quotas and costs weekly
4. Use version control: Commit before large AI operations. Use branches for experiments
5. Keep context focused: /clear or new chat between unrelated tasks