Troubleshooting Guide

Quick solutions for common Cursor issues and problems.

---

Quick Diagnosis

Problem Type	First Check
AI features not working	Check API key & subscription
Performance issues	Check indexing & memory
UI/display problems	Reset window or reinstall

---

AI Features Not Working

Tab Autocomplete Not Appearing

Symptoms:

• No suggestions when typing
• Tab key doesn't complete code

Solutions:

1. Check if Tab is enabled:

   • Cursor Settings → Features → Tab
   • Ensure "Enable Tab" is ON

2. Check file type:

   • Tab works in most code files
   • May not work in plain text or markdown

3. Restart language server:

   • Cmd+Shift+P → "Restart Language Server"

4. Clear cache:

   # macOS
   rm -rf ~/Library/Application\ Support/Cursor/Cache
   
   # Windows
   rmdir /s %APPDATA%\Cursor\Cache

---

Agent Chat Not Responding

Symptoms:

• Messages don't send
• Spinner spins forever
• "Error" message appears

Solutions:

1. Check internet connection:

   • Verify network connectivity
   • Try loading a webpage

2. Check subscription:

   • Settings → Subscription
   • Verify active Pro/Business plan

3. Check API status:

   • Visit status.cursor.com
   • Check for outages

4. Reset chat:

   • Cmd+N to start new chat
   • Clear conversation history

5. Check rate limits:

   • Pro: 500 fast requests/month
   • Business: Higher limits
   • Wait or upgrade if exceeded

---

Inline Edit (Cmd+K) Not Working

Symptoms:

• Cmd+K doesn't open prompt
• Prompt opens but no response

Solutions:

1. Check keyboard shortcut:

   • Cmd+Shift+P → "Keyboard Shortcuts"
   • Search for "Inline Edit"
   • Verify or reset binding

2. Check selection:

   • Select code for editing
   • Or place cursor for generation

3. Restart Cursor:

   • Close and reopen the application

---

Performance Issues

Slow Indexing

Symptoms:

• @Codebase searches are slow
• "Indexing..." shown for long time
• High CPU usage

Solutions:

1. Check project size:

   • Very large projects take longer
   • Add exclusions for large folders

2. Add to .cursorignore:

   node_modules/
   .git/
   dist/
   build/
   *.log

3. Reindex project:

   • Cursor Settings → Features → Codebase Indexing
   • Click "Reindex"

4. Check disk space:

   • Ensure adequate free space
   • Index stored locally

---

High Memory Usage

Symptoms:

• Cursor using excessive RAM
• System slowdown
• Frequent crashes

Solutions:

1. Close unused tabs:

   • Many open files increase memory
   • Close files not actively editing

2. Disable unused extensions:

   • Extensions → Disable those not needed

3. Reduce codebase scope:

   • Use workspace folders
   • Exclude large directories

4. Increase memory limit:

   • Settings → memory
   • Adjust if system allows

---

Slow Suggestions

Symptoms:

• Tab suggestions delayed
• Inline edit takes long time
• Agent responses slow

Solutions:

1. Check network latency:

   • Run speed test
   • Try different network

2. Use appropriate model:

   • Claude Sonnet for speed
   • GPT-4o for balance
   • Opus for quality (slower)

3. Reduce context:

   • Large files slow responses
   • Split into smaller files

---

Authentication Issues

Login Problems

Symptoms:

• Can't sign in
• "Authentication failed"
• Session expires frequently

Solutions:

1. Clear credentials:

   # macOS
   security delete-generic-password -s cursor
   
   # Windows
   cmdkey /delete:cursor

2. Use browser login:

   • If app login fails
   • Try "Sign in with browser"

3. Check SSO settings:

   • For enterprise SSO
   • Contact admin if issues

4. Reinstall Cursor:

   • Backup settings first
   • Fresh install clears auth issues

---

API Key Issues

Symptoms:

• "Invalid API key"
• Features work then stop

Solutions:

1. Verify key in settings:

   • Settings → Models
   • Check key is entered correctly

2. Generate new key:

   • Dashboard → API Keys
   • Create new, delete old

3. Check key permissions:

   • Some keys have limited access
   • Ensure proper permissions

---

UI/Display Issues

Broken Layout

Symptoms:

• Panels not showing
• Buttons missing
• Text overlapping

Solutions:

1. Reset window layout:

   • View → Reset Window Layout

2. Clear workspace state:

   • Cmd+Shift+P → "Clear Workspace Storage"

3. Reset to defaults:

   • Settings → Reset to Defaults

---

Theme/Color Issues

Symptoms:

• Wrong colors
• Unreadable text
• AI diffs hard to see

Solutions:

1. Change theme:

   • Cmd+K Cmd+T → Select theme
   • Try different theme

2. Adjust colors:

   • Settings → Colors
   • Customize specific colors

3. Check contrast settings:

   • Settings → Accessibility
   • Adjust for better visibility

---

Font/Text Problems

Symptoms:

• Font looks wrong
• Characters missing
• Sizing issues

Solutions:

1. Reset font settings:

   • Settings → Editor → Font Family
   • Clear to use default

2. Check font installation:

   • Ensure font is installed system-wide
   • Restart after installing fonts

---

Extension Issues

Extensions Not Loading

Symptoms:

• Extensions don't appear
• Features missing
• Errors in extension panel

Solutions:

1. Check compatibility:

   • Some VS Code extensions may not work
   • Check Cursor extension marketplace

2. Reinstall extension:

   • Disable → Uninstall → Reinstall

3. Clear extension cache:

   # macOS
   rm -rf ~/Library/Application\ Support/Cursor/CachedExtensions

---

Extension Conflicts

Symptoms:

• Features break when extension installed
• Multiple extensions conflict

Solutions:

1. Disable all extensions:

   • Test if issue persists
   • Enable one by one to find culprit

2. Check known conflicts:

   • Some AI extensions conflict with Cursor
   • Choose one or the other

---

MCP Server Issues

Server Not Connecting

Symptoms:

• MCP tools not available
• "Connection failed" errors

Solutions:

1. Check server configuration:

   // .cursor/mcp.json
   {
     "servers": {
       "myserver": {
         "command": "npx",
         "args": ["-y", "my-mcp-server"]
       }
     }
   }

2. Verify server is running:

   • Check if command works in terminal
   • Look for error messages

3. Restart Cursor:

   • Servers initialize on startup
   • Restart after config changes

---

Tools Not Appearing

Symptoms:

• Server connects but no tools
• Some tools missing

Solutions:

1. Check tool definitions:

   • Verify server exposes tools correctly
   • Check server documentation

2. Verify permissions:

   • Some tools may require approval
   • Check Cursor Settings → Privacy

---

Git Integration Issues

Git Features Missing

Symptoms:

• @Git not working
• No git information in chat

Solutions:

1. Verify git repository:

   • Must be inside git repo
   • Run git status to verify

2. Check git installation:

   • git --version should work
   • Install git if missing

3. Open correct folder:

   • Open repo root, not subfolder
   • Or open as workspace

---

Recovery Steps

Nuclear Option: Full Reset

If nothing else works:

1. Export settings:

   • Settings → Export Settings

2. Uninstall completely:

   # macOS
   rm -rf ~/Library/Application\ Support/Cursor
   rm -rf ~/Library/Caches/Cursor
   rm -rf ~/.cursor
   
   # Windows
   rmdir /s %APPDATA%\Cursor
   rmdir /s %LOCALAPPDATA%\Cursor
   rmdir /s %USERPROFILE%\.cursor

3. Reinstall fresh:

   • Download latest from cursor.com
   • Install and sign in

4. Import settings:

   • Settings → Import Settings

---

Getting Help

Where to Get Support

Resource	URL/Location
Documentation	docs.cursor.com
Community Forum	forum.cursor.com
Discord	discord.gg/cursor
GitHub Issues	github.com/getcursor/cursor
Email Support	support@cursor.com

Information to Include

When reporting issues:

• Cursor version (Help → About)
• Operating system and version
• Steps to reproduce
• Error messages (full text)
• Screenshots if visual issue

---

See Also

• Installation & Setup
• Codebase Indexing
• MCP Servers