Task-led troubleshooting · Cursor docs and forum checked Nov 3, 2026
Cursor Agent can’t find files? Check repository context first
A version-aware checklist for missing Cursor repository context: confirm the workspace, check ignore patterns, attach a file directly, and avoid outdated reindex advice.
Why can’t Cursor Agent find a file in my repository?
Start by confirming the file is inside an open workspace folder. Then check whether `.cursorignore`, `.gitignore`, or Cursor’s default ignore list excludes it. For one known file, attach it directly with `@path/to/file` in the prompt. Cursor’s current search docs describe Agent using local Instant Grep and normal file reading; a missing result does not by itself prove the file is absent from a semantic index.
Should I reindex my project to fix missing files?
Check your installed Cursor version before following old reindex instructions. In a September 7, 2026 forum reply, Cursor staff said recent versions had removed semantic code indexing and the Reindex/status controls; Agent instead searches files with Instant Grep and normal file reads. The same reply says a local “Index Repositories for Instant Grep” setting may remain to speed up grep. Cursor’s current troubleshooting page still lists a Reindex step, so the documentation is inconsistent. If that command or control is absent in your version, skip it; record your Cursor version and use the current search and ignore-file checks below.
How do I check whether an ignore rule hides the file?
Inspect `.cursorignore` at the workspace root and any applicable `.gitignore` rules. Cursor says both can prevent Agent from discovering a file, and its ignore-file reference lists additional default exclusions such as dependency and cache directories. Check the exact path and parent-directory patterns, including negation rules: an excluded parent directory can prevent a nested exception from taking effect. Cursor documents Git-style patterns and recommends `git check-ignore -v <path>` to identify matching Git ignore rules; inspect `.cursorignore` separately because that command only evaluates Git ignore sources.
Does @mentioning a file bypass ignore rules?
No. Cursor’s documentation says files in `.cursorignore` are blocked from Agent, codebase search, and `@` mentions. If the file is ignored, remove or narrow the matching rule only if it is appropriate for your project, then try again. Avoid pasting sensitive content into a prompt as a workaround.
What should I try when only one file or symbol is missing?
Open the file in the editor, confirm its path, and ask Agent about one exact symbol or error string while attaching `@path/to/file`. Cursor says Agent uses grep automatically for specific symbols, names, and error strings. If the direct attachment works but a broad repository question does not, include the relevant folder or symbol in the prompt and inspect ignore rules before changing indexing settings.
What should I do for a large repository or monorepo?
First narrow the workspace to the repository folders relevant to the task and exclude only known generated or irrelevant paths with `.cursorignore`. Cursor says excluding irrelevant portions can improve file discovery in large codebases or monorepos. Keep source directories needed for the task accessible, and test one representative file after changing a pattern; do not apply a blanket ignore rule that hides the code you expect Agent to inspect.
Is .cursorignore a complete security boundary?
No. Cursor says `.cursorignore` blocks listed files from Agent and Tab code access, codebase search, and `@` references, but its terminal and MCP tools cannot be restricted by that file. Cursor also says complete protection is not guaranteed. Do not treat ignore patterns as a substitute for repository permissions or secret-management controls.
What evidence supports this troubleshooting guide?
Cursor’s official forum includes user reports of “codebase not indexed” and files missing from repository search, alongside a September 2026 staff explanation that recent versions changed how search works. These are qualitative examples of recurring troubleshooting questions, not a measure of search demand or proof that a current Cursor release has a general indexing defect. Documentation checked November 3, 2026; labels and settings can change by version.
Sources
- Cursor Docs: Search and Instant Grep · checked Nov 3, 2026
- Cursor Docs: Ignore file · checked Nov 3, 2026
- Cursor Docs: Agent troubleshooting · checked Nov 3, 2026
- Cursor Forum: “How to reindexing my codebase,” staff reply Sep 7, 2026 · checked Nov 3, 2026
- Cursor Forum: “Codebase Not Indexed Error” · observed Nov 3, 2026
- Cursor Forum: “Cursor not able to read files and codebase structure?” · observed Nov 3, 2026