Cursor troubleshooting
Fix Cursor Rules Not Working
Key facts
| Scope | Cursor |
|---|---|
| Last verified | |
| Decision | Open Customize → Rules and confirm the rule is recognized. Project Rules must be `.cursor/rules/*.mdc`, not plain `.md`. Then match the intended activation mode: `alwaysApply: true`, a valid `globs` pattern, a clear relevance `description`, or an explicit `@rule-name` mention. |
| Official documentation |
Fix Cursor rules that do not load by checking file format, project scope, activation conditions and a small task that makes instruction use observable.
Open Customize → Rules and confirm the rule is recognized. Project Rules must be `.cursor/rules/*.mdc`, not plain `.md`. Then match the intended activation mode: `alwaysApply: true`, a valid `globs` pattern, a clear relevance `description`, or an explicit `@rule-name` mention.
Match the symptom
- A file under `.cursor/rules` never appears in Cursor.
- An Always rule works but a glob-scoped rule does not.
- An intelligently applied rule activates inconsistently.
- A rule affects Agent Chat but not Cursor Tab or Inline Edit.
First checks
Collect evidence before changing configuration
Customize > Rules
/create-rule
@rule-name.cursor/rules/example.mdcDiagnosis 1
Confirm Cursor recognizes the file
A Project Rule requires the `.mdc` extension and valid frontmatter; a plain `.md` file under `.cursor/rules` is ignored.
- Open Customize → Rules and locate the rule by name.
- Rename `.md` to `.mdc` only after adding valid frontmatter.
- Keep the rule inside the active workspace's `.cursor/rules` directory.
- Use `/create-rule` to generate a correctly structured starting file.
Decision: If the rule is missing from Customize, fix its path, extension, or frontmatter before testing its content.
Diagnosis 2
Match metadata to one activation mode
Cursor combines `alwaysApply`, `description`, and `globs` to decide when a Project Rule enters context.
- Use `alwaysApply: true` for every Agent chat; globs and description are ignored in this mode.
- Use a glob with `alwaysApply: false` for matching files.
- Use a description without globs for intelligent relevance selection.
- Leave both description and globs empty for manual `@` invocation.
---
globs: src/api/**/*.ts
alwaysApply: false
---
- Validate input at every API boundary.Decision: Do not combine fields hoping to make activation stronger; choose the one behavior you can test.
Diagnosis 3
Test globs against the exact workspace path
A correct-looking rule still stays absent when its glob does not match the referenced file.
- Reference a known matching file in Agent Chat.
- Compare `*.ts`, `**/*.ts`, and `src/**/*.ts` carefully.
- Use comma-separated patterns for multiple globs as documented by Cursor.
- Test one known non-matching file to prove the scope is narrow.
Decision: When the matching file activates the rule and a control file does not, glob scope is working.
Diagnosis 4
Check product surface and conflicting guidance
Cursor documents different rule coverage across Agent, Tab, and Inline Edit, while multiple active rules can contradict each other.
- Test Project Rules in Agent Chat first.
- Do not expect rules to affect Cursor Tab.
- Do not expect User Rules to apply to Inline Edit.
- Disable unrelated rules temporarily and remove duplicated or conflicting instructions.
- Replace copied style guides with linters and point to canonical code examples.
Decision: If a concise Always rule works alone, re-enable other rules in small groups to locate the conflict or context overload.
If it still fails, send this evidence
A useful support request is reproducible and does not expose credentials.
- Cursor version, operating system, and workspace root.
- Rule path, filename, and frontmatter.
- The exact file path expected to match the glob.
- Whether the test used Agent Chat, Inline Edit, or Cursor Tab.
- A minimal rule and prompt that reproduce the failure.
Related paths
Fix the adjacent layer without starting over.
Related account failures
Official sources
Commands and product behavior were checked against first-party documentation on August 13, 2026. Interfaces and authentication flows change; recheck the source when applying this across a team.