Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/cursor-pack/skills/cursor-indexing-issues/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill cursor-indexing-issues. Copyright stays with the author (MIT).

Cursor Indexing Issues

Overview

Diagnose missing, stale, slow, or over-broad codebase indexing while keeping sensitive and generated files excluded from AI context.

Prerequisites

• The affected workspace, expected file/path, current ignore configuration, and a non-sensitive reproduction.
• Authority to inspect repository indexing settings without weakening data-exclusion rules.

Instructions

1. Confirm the file is inside an approved workspace root and not intentionally excluded by ignore configuration.
2. Check index status, refresh only the affected workspace, and compare the result against a known expected file.
3. Change ignore/rule configuration through normal review, then verify both inclusion of required files and exclusion of sensitive paths.

Output

• A scoped indexing diagnosis with a verified inclusion/exclusion result.

Error Handling

Examples

When src/service.ts is absent, verify its root and ignore rules, resync indexing, then ask a minimal chat to reference only that file. If a .env file becomes visible during testing, stop and correct the exclusion before continuing.

Diagnose and fix codebase indexing problems. Covers stuck indexing, empty search results, stale results, and performance optimization for large codebases.

Quick Diagnosis

Fix: Stuck Indexing

Step 1: Reduce Scope

Create or update .cursorignore in project root:

# .cursorignore -- exclude non-essential directories

# Build output
dist/
build/
.next/
out/
target/

# Dependencies (always exclude)
node_modules/
vendor/
.venv/
venv/

# Generated / large files
*.min.js
*.min.css
*.bundle.js
*.map
*.lock
package-lock.json
yarn.lock
pnpm-lock.yaml

# Data files
*.csv
*.sql
*.sqlite
*.parquet
*.json.gz
fixtures/

# Media
*.png
*.jpg
*.gif
*.svg
*.mp4
*.woff2

Step 2: Resync Index

Cmd+Shift+P > Cursor: Resync Index

Step 3: Clear Cache (if resync fails)

# macOS
rm -rf ~/Library/Application\ Support/Cursor/Cache/
rm -rf ~/Library/Application\ Support/Cursor/CachedData/

# Linux
rm -rf ~/.config/Cursor/Cache/
rm -rf ~/.config/Cursor/CachedData/

# Windows (PowerShell)
Remove-Item -Recurse "$env:APPDATA\Cursor\Cache"
Remove-Item -Recurse "$env:APPDATA\Cursor\CachedData"

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:

1. .gitignore (Cursor respects this by default)
2. .cursorignore (explicit exclusion)
3. .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:

1. Save all open files
2. Cmd+Shift+P > Cursor: Resync Index
3. Wait for "Indexed" status to reappear
4. Retry your @Codebase query

Performance Optimization for Large Projects

Indexing Time Benchmarks

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

Memory Pressure

If Cursor runs out of memory during indexing:

// settings.json
{
  "files.maxMemoryForLargeFilesMB": 4096,
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/.git/**": true,
    "**/dist/**": true,
    "**/build/**": true
  }
}

.cursorignore vs .cursorindexingignore

Use .cursorindexingignore for files you want to reference explicitly but not have polluting search results:

# .cursorindexingignore
tests/fixtures/large-sample.json
docs/api-spec.yaml
e2e/recordings/

Enterprise Considerations

• Data residency: Embeddings stored in Turbopuffer cloud. No plaintext code stored, but metadata (obfuscated filenames) exists server-side
• Air-gapped environments: Indexing requires outbound HTTPS. Not available in fully air-gapped setups
• Index freshness SLA: 10-minute polling interval is not configurable. Manual resync is the only way to force immediate re-index
• Audit: No logging of which files are indexed. Use .cursorignore proactively for regulated data

Resources

• Codebase Indexing Docs
• Ignore Files
• Secure Codebase Indexing