title: "Troubleshooting & Reference" description: "Common issues, migration from legacy formats, YOLO mode safety, and full keyboard shortcut reference." section: "Full Guide" readTime: "8 min"

Troubleshooting & Reference

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

Migrating Legacy Config

.cursorrules → .cursor/rules/*.md

Old single-file format is deprecated. Split into typed rule files:

Before (.cursorrules):

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

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

---
type: rule
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 numbered files: 01-code-style.md, 02-testing.md, etc.
4. Add frontmatter to each: type: rule, alwaysApply: true/false
5. Delete .cursorrules

.mdc → .md

Rename all rule files if using old .mdc extension:

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

No content changes needed — just the extension.

Common Rule Mistakes

YOLO Mode Safety

YOLO mode (--dangerously-skip-permissions) runs agent actions without confirmation dialogs. Use it for CI environments, not local dev.

If you must use YOLO locally, set explicit lists:

// .cursor/settings.json
{
  "agent": {
    "allowedCommands": [
      "npm test",
      "npm run lint",
      "npm run build",
      "git status",
      "git diff"
    ],
    "deniedCommands": [
      "rm -rf",
      "git push",
      "git push --force",
      "npm publish",
      "DROP TABLE",
      "DELETE FROM"
    ]
  }
}

Rule: never run YOLO mode without an allow/deny list. The default is allow-all.

Indexing Issues

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

Diagnose: Settings → Indexing & Docs → check indexed file count and last update time.

Fixes:

Sample .cursorignore for Next.js:

.next/
node_modules/
dist/
.env*
*.log
coverage/
.turbo/

Context Drift Signs

Your session has drifted when:

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

Fix: Reset conversation. Don't try to correct drift with more prompts.

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

@relevant-file.ts @instructions.md"

Debugging Workflow Issues

Agent keeps re-implementing already solved things:

• You need the 3-file rule: reference the existing implementation
• "Don't re-implement X — it already exists in @src/lib/x.ts. Just use it."

Agent ignores type constraints:

• Make sure @types/ or the relevant type file is in your @mentions
• Add "Use ONLY the types defined in @src/types/ — do NOT invent new types" to your prompt

Generated tests don't test the right behavior:

• Provide the spec or requirements in the prompt explicitly
• Reference an existing test as pattern: @src/api/orders.test.ts (follow this structure)
• Say what behaviors must be covered: "Must test: success case, validation failure, 404, and 500 error handling"

Composer goes off on tangents:

• Use scoped prompts: one task per session
• End prompts with: "Do not change anything outside of [specific file/function]."

Keyboard Shortcuts Reference

Core

Composer Controls

Navigation

Git

Quick Reference: File Locations