Cursor

Cursor Codebase Indexing Failed — Fix the Spinning Indexer

Cursor's codebase indexing feature lets the AI search and understand your entire project, but it can silently stall or throw an error when it encounters folders that are too large or a corrupted index cache. This issue is most common in monorepos, large JavaScript projects, or any workspace where node_modules is not excluded. If the indexing spinner never stops or you see an explicit indexing failure message, the steps below will resolve it.

Why does this error happen?

Cursor builds a local vector index of your source files so the AI can answer questions about your codebase without sending every file to the cloud on each request. Indexing fails when the crawler encounters an unexpectedly large number of files — typically inside node_modules, .git, or generated build directories — causing the process to time out, exhaust memory, or write a corrupted index to the hidden .cursor folder. A stale or partially written index from a previous session can also block fresh indexing attempts, because Cursor detects the existing cache and skips re-initialization while the underlying data remains invalid.

✓

How to fix it

Delete the .cursor folder and trigger a fresh re-index

Close Cursor completely, then navigate to your project root in your file explorer or terminal and delete the hidden .cursor folder (run `rm -rf .cursor` on macOS/Linux or delete it manually on Windows). Reopen the project in Cursor and the indexer will start from a clean slate, rebuilding the vector cache without any corrupted data.

Exclude large folders using a .cursorignore file

Create a file named .cursorignore in your project root and add glob patterns for directories that do not need to be indexed, such as dist/, build/, .cache/, and any vendor or generated-code folders. This file follows the same syntax as .gitignore, so you can copy patterns directly from there to keep the indexed file count manageable and prevent future timeouts.

Confirm node_modules is excluded from indexing

Cursor should skip node_modules by default, but verify this is the case by opening Settings → Features → Codebase Indexing and checking the ignore list, or by ensuring node_modules is listed in your .cursorignore. Indexing a typical node_modules directory can add hundreds of thousands of files and is the single most common cause of indexing failures in JavaScript and TypeScript projects.

Re-open the project root folder instead of a subfolder

Cursor must be opened at the true root of your project — the directory that contains your .git folder — for the indexer to correctly scope the file tree. If you opened a nested subfolder, close the window and use File → Open Folder to select the actual project root, then wait for the indexing status indicator in the bottom bar to show a completed state.

💡 Pro Tip

Add a .cursorignore file to your project template or repository from day one — mirroring the patterns in your .gitignore — so that every developer who clones the project gets fast, successful indexing without any manual configuration.

Frequently Asked Questions

How do I know when Cursor has finished indexing my codebase?

Look at the status bar at the bottom of the Cursor window; it displays an indexing progress indicator that changes to a checkmark or disappears when indexing is complete. You can also go to Settings → Features → Codebase Indexing to see the total number of indexed files and the current status.

Will deleting the .cursor folder remove my settings or keybindings?

No — your Cursor settings, keybindings, and extensions are stored separately in your user profile directory, not inside the project-level .cursor folder. Deleting .cursor only removes the local codebase index cache and any project-specific AI conversation history stored there.

Can I manually trigger re-indexing without deleting the .cursor folder?

Yes — open the Command Palette with Cmd/Ctrl+Shift+P and search for 'Cursor: Reindex Codebase' to force a fresh index pass without deleting the folder. If the indexer is stuck in a corrupted state, however, a full deletion of the .cursor folder is the more reliable fix.

Does codebase indexing work on very large monorepos?

Cursor can handle large monorepos, but you should aggressively exclude packages or workspaces that are not relevant to your current work using .cursorignore. Cursor Pro accounts also benefit from higher indexing limits and faster processing compared to the free tier.

✓

Quick diagnostic checklist

Before diving into the full fix, run through these quick checks — they resolve the issue in most cases without additional steps:

1.Restart the Cursor application completely

2.Check your Cursor subscription is active at cursor.com/account

3.Update Cursor to the latest version via Help → Check for Updates

4.Disable conflicting VS Code extensions

5.Re-enter your API key in Cursor Settings → Models

Common root causes

Understanding why this error occurs helps you prevent it in the future. The most frequent causes are:

Outdated Cursor version with known bugs
API key expired or quota exhausted
Conflicting VS Code extensions interfering with Cursor
Context window exceeded in large files or codebases
Network proxy or firewall blocking Cursor API calls

Still not working?

If none of the steps above resolved the issue, the next step is to contact Cursor support directly. When reaching out, include:

• The exact error message or code you see
• The steps you already tried from this guide
• Your account plan and the approximate time the error started
• Your browser/OS version if it is a web interface issue

Open Cursor Forum →

About Cursor

Cursor is an AI-powered code editor built on VS Code, developed by Anysphere Inc. It integrates GPT-4 and Claude models directly into the editor for autocomplete, code generation, and natural language chat. Cursor is popular among developers for pair programming and large codebase navigation.

Browse all Cursor error guides →

Cursor →