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?
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.