Troubleshooting

Reference intermediate

Common Cursor Problems and Solutions

Problem: Autocomplete Suggestions Are Irrelevant

Symptoms: Tab completions suggest code that does not match your project patterns, uses wrong libraries, or is completely off-base.

Cause: Insufficient project context; Cursor is relying on general training data rather than your codebase patterns.

Solution:

  • Create a .cursor/rules file with project conventions
  • Ensure relevant files are open in editor tabs (Cursor uses open files as context)
  • Add type definitions for custom utilities
  • Check that .cursorignore is not excluding important reference files

Problem: Chat Does Not Know About Recent File Changes

Symptoms: AI references old versions of code or says things exist that you have already deleted.

Cause: Cursor's indexing may be stale or the chat context does not include unsaved files.

Solution:

  • Save all files before prompting (Cmd+S / Ctrl+S)
  • Re-index the project: Command Palette > "Cursor: Reindex"
  • Use @file to explicitly reference the current file
  • Start a new chat session to clear stale context

Problem: Inline Edit (Cmd+K) Replaces Too Much Code

Symptoms: A targeted edit request rewrites the entire function or surrounding code you did not want changed.

Cause: Selection was too broad, or the prompt was ambiguous about scope.

Solution:

  • Select only the exact lines you want modified
  • Be explicit: "Only change the return statement" or "Only modify line 15-20"
  • Use chat instead for surgical changes in complex functions
  • Undo immediately (Cmd+Z) and retry with a more precise selection

Problem: Agent/Agent Makes Unwanted Changes to Other Files

Symptoms: Agent mode modifies files you did not mention or makes "improvements" you did not request.

Cause: Agent inferred that related files needed updates; overly broad instructions.

Solution:

  • Be explicit about scope: "Only modify files in src/components/auth/"
  • Review each file in the diff view before accepting
  • Use "Reject" on individual files while accepting others
  • Add constraints: "Do not modify any existing files, only create new ones"

Problem: AI Cannot Find Code with Agent mode

Symptoms: Agent mode returns "I couldn't find..." for code that definitely exists in your project.

Cause: File is in .cursorignore, indexing is incomplete, or file type is not indexed.

Solution:

  • Check .cursorignore for overly broad patterns
  • Run reindex: Command Palette > "Cursor: Reindex"
  • Use @file with the exact path instead
  • Ensure the file extension is a recognized code type
  • Wait for indexing to complete (check status bar)

Problem: Cursor Is Slow or Unresponsive

Symptoms: Editor lags, AI responses are slow, high CPU/memory usage.

Cause: Large project without proper ignoring; too many files indexed; many extensions.

Solution:

  • Add comprehensive .cursorignore:
    node_modules/
.git/
dist/
build/
*.min.js
*.map
  • Disable unnecessary VS Code extensions
  • Close unused editor tabs (reduces context computation)
  • Restart Cursor: Command Palette > "Developer: Reload Window"

Problem: .cursor/rules File Is Not Being Applied

Symptoms: AI ignores project conventions specified in .cursor/rules.

Cause: File is in wrong location, has syntax errors, or is too large to fit in context.

Solution:

  • Verify file is at project root (same level as package.json)
  • Filename must be exactly .cursor/rules (no extension)
  • Keep file under 500 lines (context window limits)
  • Test by asking: "What are the project rules?" in chat
  • Try the newer .cursor/rules/ directory format for organized rules

Problem: Generated Code Has Import Errors

Symptoms: AI writes imports from packages not in your project or uses wrong import paths.

Cause: AI does not always check package.json or your path aliases.

Solution:

  • Include in .cursor/rules: "Only import from packages listed in package.json"
  • Reference @file:tsconfig.json for path aliases
  • Reference @file:package.json for available dependencies
  • Specify: "Use relative imports, not path aliases" (or vice versa)

Problem: Chat Context Is Too Small for Large Tasks

Symptoms: AI truncates responses, forgets earlier parts of the conversation, or produces incomplete code.

Cause: Context window is exhausted by file references and conversation history.

Solution:

  • Use Agent (Cmd+I) for multi-file tasks (larger context)
  • Break the task into smaller, focused conversations
  • Remove unnecessary @file references that are not essential
  • Summarize previous decisions rather than keeping full chat history
  • Use @folder sparingly (it consumes a lot of context)

Problem: Diff View Shows Confusing Changes

Symptoms: Hard to understand what Cursor actually changed; diff includes formatting changes mixed with logic changes.

Cause: AI reformatted code while making targeted changes.

Solution:

  • Add to .cursor/rules: "Do not reformat code you did not change"
  • Use a formatter (Prettier) after accepting so only logic changes show in git diff
  • Review changes in git diff rather than Cursor's diff view for clarity
  • Be specific: "Change only the logic, do not modify formatting or whitespace"