Manage troubleshoot Cursor codebase indexing problems. Triggers on "cursor indexing",
"cursor index", "cursor codebase", "@codebase not working", "cursor search broken". Use when working with cursor indexing issues functionality. Trigger with phrases like "cursor indexing issues", "cursor issues", "cursor".
Diagnose and fix codebase indexing problems. Covers stuck indexing, empty search results, stale results, and performance optimization for large codebases.
Restart Cursor after clearing cache. Full re-index begins automatically.
Fix: @Codebase Returns No Results
Check 1: Is Indexing Complete?
Look at the bottom status bar. If it says "Indexing...", wait for it to finish. For projects with 10K+ files, initial indexing can take 10-30 minutes.
Check 2: Is the File Excluded?
A file might be excluded by:
.gitignore (Cursor respects this by default)
.cursorignore (explicit exclusion)
.cursorindexingignore (excluded from index but not from AI features)
Verify: Cursor Settings > Features > Codebase Indexing > View included files
This opens a text file listing all indexed paths. Search for the file you expect to find.
Check 3: Network Connectivity
Indexing requires network access to Cursor's embedding API. Test:
Can you access api.cursor.com?
Is a corporate proxy blocking outbound HTTPS?
Is a VPN interfering?
Check 4: Semantic vs Keyword Search
@Codebase uses semantic search (embeddings), not keyword matching. The query "authentication middleware" will find files about auth even if they never use the word "middleware." But it may miss files if the semantic meaning is very different from the query.
For exact keyword matching, use Cmd+Shift+F (workspace search) instead.
Fix: Stale / Outdated Results
Cursor re-checks for file changes every 10 minutes using a Merkle tree. If you need fresher results:
Save all open files
Cmd+Shift+P > Cursor: Resync Index
Wait for "Indexed" status to reappear
Retry your @Codebase query
Performance Optimization for Large Projects
Indexing Time Benchmarks
Project Size
Files Indexed
Initial Index Time
Small (< 1K files)
~500
< 30 seconds
Medium (1K-10K files)
~5,000
1-5 minutes
Large (10K-50K files)
~20,000
5-30 minutes
Very large (50K+)
~50,000+
30 min - 2 hours
Monorepo Strategy
Do not open the entire monorepo root. Instead:
# Open just the package you're working on:
cursor packages/api/
# Or use .cursorignore to exclude other packages:
# .cursorignore
packages/web/
packages/mobile/
packages/admin/
packages/deprecated-*
Linux File Watcher Limits
If indexing crashes on Linux with large projects:
# Check current limit
cat /proc/sys/fs/inotify/max_user_watches
# Increase to 524288 (persists across reboots)
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
