# Cursor Indexing Debugging Guide

**Last Updated:** 2026-02-12

Step-by-step guide for debugging Cursor indexing when the index count remains high after optimization.

## When to Use This Guide

- Cursor UI shows ~9,400+ files after Delete Index + Sync (target: 5.7k–6.2k)
- Script `estimated_cursor_index` is ~6,200 but Cursor UI shows much higher
- Ignore patterns appear correct but index doesn't reduce

## 1. Find embeddable_files.txt

Cursor stores the actual indexed file list at:

**macOS:**
```
~/Library/Application Support/Cursor/User/workspaceStorage/*/anysphere.cursor-retrieval/embeddable_files.txt
```

**Linux:**
```
~/.config/Cursor/User/workspaceStorage/*/anysphere.cursor-retrieval/embeddable_files.txt
```

**Windows:**
```
%APPDATA%\Cursor\User\workspaceStorage\*\anysphere.cursor-retrieval\embeddable_files.txt
```

There may be multiple workspace directories. Use the one for your project (most recently modified).

## 2. Export and Diff

After running **Delete Index** then **Sync** in Cursor:

```bash
# Export Cursor's actual index
python3 v2/scripts/dev-helpers/export-cursor-indexed-files.py

# Diff against expected (from ignore simulation)
python3 v2/scripts/dev-helpers/diff-index-vs-expected.py
```

Or use the analyze script with compare:

```bash
python3 v2/scripts/dev-helpers/analyze-cursor-index.py --compare-with docs/development/cursor-indexed-files-export.txt
```

Review `docs/development/cursor-index-diff-report.txt`:
- **Violations** = files Cursor indexes that should be excluded (check `.cursorindexingignore` patterns)
- **Missing** = files we expect indexed but Cursor excludes (check for over-exclusion)

## 3. Check Cursor Logs

1. **Open Output panel:** `Cursor` > `Terminal` > `Output`
2. **Select "Cursor Indexing & Retrieval"** from the dropdown
3. Re-run Delete Index + Sync
4. Look for errors or warnings during indexing

## 4. Enable Trace Logging

1. Command Palette: `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux)
2. Type **"Developer: Set Log Level"**
3. Select **Trace**
4. Re-run Delete Index + Sync
5. Check Output > Cursor Indexing & Retrieval for pattern application details

## 5. View Included Files

Cursor Settings > Indexing & Docs > **View included files** – saves a `.txt` export. Compare with the script's expected list to identify discrepancies.

## 6. Clean-Slate Workaround

If Cursor ignores rules for large codebases ([forum report](https://forum.cursor.com/t/indexing-issue-will-not-index-using-the-cursor-ignore-file/46359)):

1. Close Cursor
2. Rename project folder (e.g. `landingpage` → `landingpage-temp`)
3. Reopen the renamed folder in Cursor
4. Delete Index + Sync
5. Rename back if needed

## 7. Verify Pattern Syntax

```bash
python3 v2/scripts/dev-helpers/verify-index-config.py --verbose
python3 v2/scripts/dev-helpers/verify-index-config.py --check-unused
```

- `--verbose` shows which pattern matched each test path
- `--check-unused` reports patterns that match no tracked files (possible typos or fallbacks)

## Debugging Flowchart

```
Index still high after Delete Index + Sync
    │
    ├─► Export embeddable_files.txt (export-cursor-indexed-files.py)
    │
    ├─► Run diff-index-vs-expected.py
    │       │
    │       ├─► Many violations? → Check .cursorindexingignore patterns
    │       │   → Try simplified patterns (see CURSOR_INDEXING_SETUP.md)
    │       │
    │       └─► Few violations? → Check Cursor logs for errors
    │
    ├─► Check Cursor Indexing & Retrieval logs
    │
    ├─► Try clean-slate workaround (rename folder)
    │
    └─► Last resort: Move exclusions to .cursorignore (lose @-mentionability)
```

## Related

- [CURSOR_INDEXING_OPTIMIZATION.md](CURSOR_INDEXING_OPTIMIZATION.md) – Troubleshooting section
- [CURSOR_INDEXING_SETUP.md](CURSOR_INDEXING_SETUP.md) – Pattern quirks
- [PRE_INDEX_CHANGE_CHECKLIST.md](PRE_INDEX_CHANGE_CHECKLIST.md) – Before/after change steps