title: "Troubleshooting & Reference" description: "Common issues, migration from legacy formats, Run Modes safety, and keyboard shortcut reference." section: "Full Guide" readTime: "7 min"

Troubleshooting & Reference

Quick fixes for common Cursor issues and a short keyboard shortcut reference.

Migrating Legacy Config

.cursorrules → .cursor/rules/*.mdc or AGENTS.md

The single-file .cursorrules format is the legacy approach. Split it into rule files with frontmatter, or move simple instructions into AGENTS.md.

Before (.cursorrules):

Always use TypeScript.
Never use any type.
Use Tailwind for styling.

After (.cursor/rules/01-code-style.mdc):

---
description: Code style conventions
alwaysApply: true
---
 
# Code Style
 
- Always use TypeScript
- Never use `any` type — use `unknown` and narrow
- Use Tailwind CSS for all styling — no inline styles

Steps:

1. Read .cursorrules contents
2. Group by category (style, testing, patterns, etc.)
3. Create files such as 01-code-style.mdc, 02-testing.mdc
4. Add frontmatter to each: alwaysApply: true, or globs, or a description for agent-decided rules
5. Delete .cursorrules

Rule files must be .mdc

Project rules in .cursor/rules/ use the .mdc extension. Plain .md files in that folder are not loaded as rules. If you have .md rule files, rename them:

# In your .cursor/rules/ directory
for file in *.md; do mv "$file" "${file%.md}.mdc"; done

No content changes needed. If you just want plain markdown with no frontmatter, use AGENTS.md instead.

Common Rule Mistakes

Run Modes Safety

Run Modes control how much autonomy the agent has for shell, MCP, and Fetch calls. Set them in Settings > Agents > Approvals & Execution. (The older informal name "YOLO mode" roughly corresponds to Run Everything.)

Rule: don't use Run Everything on a machine with credentials or production access. Prefer Auto-review or Allowlist.

The sandbox limits where terminal commands can read, write, and connect. By default workspace files are accessible and protected paths such as .git/hooks are guarded. Customize it with sandbox.json in ~/.cursor/ (all projects) or <project>/.cursor/ (one project). Auto-review reads permissions.json from the same locations, and team dashboard settings override both.

For hard guarantees, add a beforeShellExecution hook that denies dangerous commands:

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/guard-shell.sh",
        "matcher": "rm |git push|npm publish",
        "failClosed": true
      }
    ]
  }
}

The script reads JSON on stdin and prints {"permission": "deny"} (or allow / ask). Exit code 2 also blocks the action.

Indexing Issues

Symptom: Responses are slow, search misses files, the agent doesn't know about recent changes.

Diagnose: Open Cursor Settings > Indexing and check what's included.

Fixes:

Sample .cursorignore (on top of the built-in defaults, which already cover .gitignore, node_modules/, and .env*):

secrets/
**/*.pem
*.generated.ts

Context Drift Signs

Your session has drifted when:

• Agent ignores rules it was following earlier
• Suggestions repeat a mistake you already corrected
• Agent proposes patterns that don't match your codebase style
• Responses get worse over time in the same session

Fix: Start a new chat. Don't try to correct drift with more prompts.

# Start a fresh chat with:
"Continuing [specific task].
Previous session: [2-3 bullet summary of what was done]
Next step: [exactly one thing]

@relevant-file.ts"

You can also attach the old conversation with @Chats.

Debugging Workflow Issues

Agent keeps re-implementing already solved things:

• Reference the existing implementation: "Don't re-implement X — it already exists in @src/lib/x.ts. Just use it."

Agent ignores type constraints:

• Attach the relevant type file
• Add "Use ONLY the types defined in @src/types/ — do NOT invent new types"

Generated tests don't test the right behavior:

• Provide the spec explicitly
• Reference an existing test as the pattern: @src/api/orders.test.ts
• Say what must be covered: "Must test: success case, validation failure, 404, and 500 error handling"

Agent goes off on tangents:

• One task per chat
• End prompts with: "Do not change anything outside of [specific file/function]."
• Use Plan Mode (Shift+Tab) first for ambiguous tasks
• Restore a checkpoint (restores files, not chat history) or git restore if it went too far

Elusive or intermittent bug: switch to Debug Mode from the mode picker.

Tab suggestions are annoying or wrong: click the Tab indicator in the bottom-right corner to snooze it or disable it for certain file types.

Keyboard Shortcuts Reference

Windows/Linux keys shown; on macOS use Cmd for Ctrl and Option for Alt. The full list is in the keyboard shortcut reference.

Quick Reference: File Locations