Cursor Rules Not Being Loaded (.cursorrules / .cursor/rules)

You wrote use 4-space indent, never use any into a rule, and Cursor’s Agent still hands you 2-space code full of any. Ask it “what rules do you see?” and it says none.

As of June 2026 the single most common reason is the format. Cursor deprecated the legacy single-file .cursorrules (back in 0.43) and in Cursor 2.x the Agent does not read .cursorrules at all — it only honors the newer Project Rules: .mdc files inside .cursor/rules/. So a .cursorrules that “worked last year” can silently stop applying after an update.

Fastest fix: move your rules into .cursor/rules/style.mdc with valid frontmatter (alwaysApply: true), then confirm it shows up in Cursor Settings → Rules, Commands. If it is listed there, it loads; if it is missing, your frontmatter is broken.

Which bucket are you in?

Symptom	Likely cause	Jump to
Rules live in .cursorrules at root, Agent ignores them	Legacy format not read in Agent mode	Cause 1
File is .cursor/rules/foo.md (not .mdc)	Wrong extension, silently ignored	Cause 2
.mdc exists but not in Settings → Rules	Broken/missing frontmatter, silently dropped	Cause 2
Rule is listed but never auto-applies	No alwaysApply/globs trigger	Cause 3
Rules sit in a subfolder of a big repo	Scope/location mismatch	Cause 4
Worked, then suddenly stopped after editing	Stale rules cache	Cause 5
Garbled first line / parse failure	UTF-8 BOM	Cause 6
git check-ignore matches the file	Hidden by .cursorignore	Cause 7

Common causes

1. Still using legacy .cursorrules

.cursorrules (one file at repo root) is deprecated. It is still parsed in some modes, but Cursor 2.x Agent ignores it — this is a deliberate change so Agent uses only the scoped Project Rules system. If your team upgraded Cursor and rules quietly stopped applying, this is almost always why.

How to judge: your rules are in .cursorrules, you are in Agent mode, and Cursor Settings → Rules, Commands does not list them. Migrate to .cursor/rules/*.mdc (see Step 1).

2. Wrong extension or broken frontmatter

Project rules must be .mdc files inside .cursor/rules/. Two traps:

• A plain .md file in .cursor/rules/ is ignored by the rules system — it has no rule frontmatter.
• If the YAML frontmatter has any error, Cursor silently skips the file with no warning, log, or error popup. The usual culprits:
  • Missing the closing --- line.
  • globs written as a single string instead of an array.
  • YAML is case-sensitive: True is not true, so alwaysApply: True never loads.

How to judge:

ls .cursor/rules/
# every rule must end in .mdc, not .md

Then open Cursor Settings → Rules, Commands. If the .mdc file exists on disk but is not listed in that panel, the frontmatter is malformed.

3. .mdc rule has no trigger condition

.mdc frontmatter has three fields that decide when a rule fires. As of June 2026 Cursor exposes four rule types:

Rule type	Frontmatter	When it applies
Always	alwaysApply: true	Every chat/Agent request
Auto Attached	alwaysApply: false + globs: [...]	When an edited/attached file matches a glob
Agent Requested	alwaysApply: false + description (no globs)	Agent decides from the description
Manual	none of the above	Only when you @-mention the rule

A rule with only a description and no alwaysApply/globs is a Manual rule — it never auto-injects, so it looks “not loaded” until you @-mention it.

How to judge:

---
description: Use 4-space indent
# no alwaysApply, no globs → Manual → never auto-applies
---

4. Rules in the wrong scope

Cursor reads .cursor/rules/ at the workspace root and nested .cursor/rules/ folders inside subdirectories (and nearby AGENTS.md files), with more specific/nearer rules taking precedence. The failure mode is opening the wrong folder as your workspace: if you open ~/code/monorepo but the rule lives in packages/web/.cursorrules, a legacy single file in a subfolder won’t apply project-wide.

How to judge: the title bar / bottom-left shows your workspace path; confirm a rules file resolves from there.

pwd
ls -la .cursorrules .cursor/rules/ 2>/dev/null

In a monorepo, put shared rules in the root .cursor/rules/ and package-specific rules in packages/<name>/.cursor/rules/.

5. Rules cache hasn’t refreshed

After adding or editing a rule, the running window may keep serving the old version until the window reloads.

How to judge: you just edited a rule, nothing changed; after Developer: Reload Window it works = cache.

6. Encoding isn’t UTF-8 or has a BOM

Windows Notepad defaults to UTF-8 with BOM. A leading BOM can break frontmatter parsing so the rule is dropped (same silent-skip as cause 2).

How to judge:

file .cursor/rules/style.mdc
# expect: "...: UTF-8 Unicode text"
# bad:    "...: UTF-8 Unicode (with BOM) text"

hexdump -C .cursor/rules/style.mdc | head -1
# starts with ef bb bf = BOM

7. Rules hidden by .cursorignore

Some teams .gitignore .cursorrules as a personal preference and accidentally add it to .cursorignore too. Cursor’s own ignore list makes it skip the file.

How to judge:

git check-ignore .cursorrules .cursor/rules/style.mdc
grep -i cursorrules .cursorignore 2>/dev/null

Before you start

• Pick one format: new .cursor/rules/*.mdc (recommended; works in all modes including Agent). The legacy .cursorrules only lingers for backward compatibility and Cursor has said it will be removed.
• Commit before editing rules so a failed load can be diagnosed against a clean baseline.
• Note your Cursor version: Cursor → About (the .mdc system has been the default for some time, but the Agent-only-reads-.mdc behavior is what bites recent upgraders).

Shortest fix path

Format → trigger → cache.

Step 1: Migrate to .cursor/rules/*.mdc

Create the directory and one rule file. The fastest way is the built-in generator:

• In Agent chat, type /create-rule, or
• Cursor Settings → Rules, Commands → + Add Rule.

Or write it by hand:

.cursor/rules/style.mdc
---
description: TypeScript style rules
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---
- Use 4-space indent
- Never use `any` — use `unknown` or specific types
- Prefer `interface` over `type` for object shapes

Watch the YAML: closing --- present, globs is an array, booleans are lowercase true/false.

Step 2: Confirm it’s registered

Open Cursor Settings → Rules, Commands. Your rule should appear in the list with its type (Always / Auto Attached / Agent Requested / Manual). If it is not listed, the frontmatter is broken — fix it and the entry appears immediately. This panel is the source of truth for “did the rule load.”

Step 3: Strip BOM, force UTF-8

file .cursor/rules/style.mdc

# Strip BOM if present
sed -i.bak '1s/^\xEF\xBB\xBF//' .cursor/rules/style.mdc
# Or in Cursor: bottom-right status bar shows "UTF-8 with BOM" → click → "Save with Encoding" → "UTF-8"

Step 4: Reload to flush the cache

Cmd+Shift+P → "Developer: Reload Window"

If still stale, wipe the workspace cache (close Cursor first):

# macOS
rm -rf ~/Library/Application\ Support/Cursor/User/workspaceStorage/<this-workspace-hash>

Step 5: Ask the Agent to enumerate rules

In a new chat:

List every active Cursor rule you can see right now, including their source files and any conditions on activation.

Lists your rule = loaded. “No rules” = still failing, go back to Step 2.

How to confirm it’s fixed

• The rule appears in Cursor Settings → Rules, Commands and shows a sensible type.
• The chat input shows the Rules indicator with your rule included in context for that request.
• Generated code respects the rule (indent / naming / imports).
• A teammate opening the same repo on a fresh clone sees the same rule applied — proving it’s committed and not local-only.

If it still fails

• Reduce the rule to one unmistakable line like Always begin every reply with the word HELLO. with alwaysApply: true. If obeyed → rules load and your real issue is the rule’s wording, not loading.
• Verify the file is genuinely .mdc, not .md or .mdc.txt (Windows hidden extensions).
• Roll back the latest Cursor upgrade or rules edit to isolate the change.
• Search the official forum at forum.cursor.com for “rules not applied”; include Cursor version, file path, and the Settings → Rules state.
• Check View → Output and select the Cursor channel for rules-loading logs, then file under Bug Reports.

FAQ

Does .cursorrules still work in 2026? Partially. It is deprecated and, in Cursor 2.x, the Agent ignores it. Use .cursor/rules/*.mdc so rules apply in Chat, Composer, and Agent alike.

Why is my rule on disk but not in Settings → Rules? The frontmatter is malformed and Cursor skipped it silently. Check for a missing closing ---, globs written as a string instead of an array, or True/False instead of lowercase true/false.

My rule loads but never auto-applies — why? It’s probably a Manual rule (only a description, no alwaysApply or globs). Add alwaysApply: true for always-on, or globs: ["**/*.ts"] to auto-attach by file type.

Where do rules go in a monorepo? Shared rules in the root .cursor/rules/; package-specific rules in packages/<name>/.cursor/rules/. Nearer rules take precedence over root rules for files in that subtree.

Do I need AGENTS.md as well? No. AGENTS.md is an alternative Cursor honors (nearest-file-wins by directory). Pick .cursor/rules/*.mdc for glob/always-on scoping, or AGENTS.md for simple plain-text guidance. Don’t maintain both for the same rules.

Prevention

• After adding a rule, immediately open Settings → Rules, Commands and ask in chat “what rules do you see?” Don’t wait to be surprised.
• Standardize on .cursor/rules/*.mdc with explicit alwaysApply: true; retire .cursorrules.
• Edit rules in Cursor / VS Code, never Notepad — avoids BOM.
• Commit team rules to git; don’t .gitignore them. Use User Rules in settings for personal preferences.
• After every rules edit, Cmd+Shift+P → Developer: Reload Window to bust the cache.

Related reading

• Cursor suggestions ignore conventions
• Cursor config conflicts with VS Code workspace settings
• Cursor model list out of date
• Cursor Composer made sweeping wrong edits
• Cursor generates duplicate logic

Tags: #Cursor #Troubleshooting

Related Articles

Troubleshooting

Cursor Auto Routes a Hard Task to a Weak Model

Cursor's Auto router sends a complex refactor to a small model and you get shallow edits. Diagnose the routing signals and force the right model for hard tasks.

May 24, 2026 #Cursor #Troubleshooting

Troubleshooting

Cursor Chat or Composer History Missing After Restart

Cursor reopens with an empty chat list, only the latest thread, or stuck on 'Loading Chat'. Usually a workspace-hash change, a botched update migration, or a corrupted state.vscdb. How to recover and prevent it.

May 24, 2026 #Cursor #composer

Troubleshooting

Cursor Cmd-K Inline Edit Spinner Never Returns: Fix It

Cmd-K (Ctrl+K) spins forever or shows "Taking longer than expected…" with no diff. The fast fix: Reload Window or update Cursor. Walk the six verified causes.

May 24, 2026 #Cursor #Troubleshooting

Troubleshooting

Fix Cursor Extensions: Network Error or Empty Marketplace

Cursor's Extensions panel shows a network error, empty list, or a stuck spinner. Cursor uses Open VSX, not Microsoft's marketplace. Pick the right cause and fix it fast.

May 24, 2026 #Cursor #extensions

Troubleshooting

Cursor MCP Server Shows Disconnected or No Tools

Added an MCP server in Cursor but it stays disconnected, or no tools appear in chat. 90% of the time it's a bad PATH, a JSON typo, or a stdout leak. Diagnose and fix in five minutes.

May 24, 2026 #Cursor #mcp

Troubleshooting

Cursor Python Venv Not Detected (Wrong Interpreter)

Cursor uses system Python instead of your project venv, breaking imports, linting, and agent edits. Fix the interpreter picker, venv discovery, shell PATH, and the new Python Environments panel.

May 24, 2026 #Cursor #Troubleshooting