Cursor’s Agent (or Composer) gives you an answer, you expand the context panel at the top of the chat, and utils/parseInvoice.ts — the file you know is relevant — isn’t on the list. That panel is the actual file set handed to the model. Not in the panel means the model never saw it.
This is almost never a bug. It’s one of a few classic retrieval failures: the file scored too low in semantic search, it’s blocked by .cursorignore, it was edited too recently to be re-indexed, or unrelated files crowded it out.
Fastest fix (5 seconds): in the chat input, type @ then the filename (e.g. @parseInvoice), let autocomplete attach it, and resend. A manually attached file is always handed to the model. The one exception: if the file is listed in .cursorignore, @ won’t attach it either — see cause 2 below.
Then fix the root cause so you stop babysitting it.
Which bucket are you in?
| Symptom in the panel | Most likely cause | Jump to |
|---|---|---|
File never appears, even when you type @ | Blocked by .cursorignore | Cause 2 |
File appears if you @ it, but auto-retrieval skips it | Low semantic score / generic name | Cause 1 / Cause 5 |
| File you just created/renamed is missing | Not re-indexed yet | Cause 3 |
| Wrong same-named file shows instead | Generic filename collision | Cause 5 |
| Panel is full of unrelated tabs/recent files | Context crowded out | Cause 4 |
.parquet / .bin / huge file missing | Not indexable | Cause 6 |
Common causes
1. Semantic retrieval scored it too low
Cursor splits each file into chunks, embeds them as vectors, and stores them in a vector index for semantic search (@codebase and the Agent’s automatic file lookup both run on this). A 500-line utils.ts of mixed helpers dilutes the “parse invoice” similarity; the same code in a file named parseInvoice.ts lights up the filename signal and jumps to the top of the results.
How to confirm: git mv utils.ts parseInvoiceHelpers.ts, run a resync (see Step 3), then re-check the panel.
2. Blocked by .cursorignore
This is the cause people misdiagnose most. As of June 2026, .cursorignore is a hard block: a file matched by it is excluded from semantic search, from Tab, from Agent and Inline Edit, and from @-mention references. So if your “fastest fix” of typing @filename silently does nothing, the file is almost certainly in .cursorignore.
There is a separate, softer file: .cursorindexingignore. Files matched there are kept out of the search index (so they won’t show up via auto-retrieval) but stay reachable by @-mention and the Agent. That’s usually what you actually want for big generated dirs you occasionally need to reference.
Common over-reach in .cursorignore: dist/, build/, generated/ — which often hold the schemas and type definitions the model should reference.
How to confirm:
cat .cursorignore
git check-ignore -v src/utils/parseInvoice.tsgit check-ignore names the .gitignore rule that excludes a file (Cursor also honors .gitignore). For a .cursorignore-specific rule it won’t print, so eyeball .cursorignore directly. Note: precedence is .gitignore first, then .cursorignore (with ! negation supported), then .cursorindexingignore on top for index-only exclusion.
3. File was just created or renamed
Indexing is incremental: Cursor uses a Merkle-tree change detector and auto-resyncs only changed files on a polling cycle (a few minutes, roughly every 5-10 min as of June 2026 and not user-configurable). A brand-new file needs a save event to register, and a rename can leave the old path lingering in the index for a few seconds. During that window, retrieval is working off the stale index.
How to confirm: open Cursor Settings → Indexing and compare the indexed file count to git ls-files | wc -l. If it’s short, the index hasn’t caught up — force it (Step 3).
4. Context crowded out by noise
The model’s context window is finite. The Agent/Composer auto-pulls “recent edits,” “open tabs,” and imported files; too many of those eat the budget and evict your target file.
How to confirm: the panel shows a dozen unrelated tabs or recently-edited files. That’s the giveaway.
5. Generic filename splits the signal
index.ts, helpers.ts, types.ts, utils.ts — a monorepo has dozens of each, and semantic search picks the wrong sibling.
How to confirm: the panel shows a same-named file but the wrong path.
6. Binary, very large, or unsupported file
Binary blobs (.parquet, .bin, .gz) aren’t embeddable, and very large text files are skipped during chunking. A regular .ts/.json that has grown into the megabytes can quietly fall out of the index.
How to confirm: ls -lh path/to/file. If it’s a binary type or an unexpectedly large text file, it won’t be in the semantic index — attach it with @ instead, or split it.
Before you start
- Identify the entry point that misbehaved: Agent / Composer / Cmd+K / chat. Cmd+K (inline edit) works on the current file and selection, not repo-wide retrieval, so a “missing” repo file there is expected.
- Commit first before touching renames or ignore rules, so you don’t trash shared team config.
- Note your Cursor version and active model (e.g. Sonnet 4.6, GPT-5.5, Composer). Retrieval ranking shifts between versions.
Info to collect
- Cursor version, OS, total file count in the repo.
- Full
.cursorignoreand.cursorindexingignore; relevant.gitignoreentries. - A screenshot of Cursor Settings → Indexing (indexing status, last sync, indexed file count).
- A screenshot of the chat context panel (the actual list of loaded files).
- Path, size, and extension of the missing file.
Shortest fix path
Ordered “instant rescue → systemic improvement.”
Step 1: Manually attach with @
Fastest. In the chat input type @parseInvoice, let autocomplete attach the file, then send. A manually attached file is always handed to the model — about 5 seconds. (If @ won’t attach it, jump to Step 2: it’s .cursorignored.)
Step 2: Audit .cursorignore
cat .cursorignore
git check-ignore -v src/utils/parseInvoice.tsIf the file is being blocked:
- Quick: comment out the offending rule, reload Cursor (Cmd+Shift+P → “Reload Window”), retry.
- Better: if you only wanted the file out of search (not blocked from the model entirely), move the rule from
.cursorignoreto.cursorindexingignore. The file then stays@-mentionable. - Tighter glob: use
dist/**/*.jsinstead ofdist/so generated.d.tstypes stay visible.
Step 3: Resync the index
Cmd+Shift+P → “Cursor: Resync Index” (older builds label this “Cursor: Rebuild Index” / “Rebuild Codebase Index”). This forces an immediate re-index instead of waiting for the automatic cycle. A full rebuild on a large repo can take several minutes; semantic search comes back online well before the index is fully complete. Do this after big renames or bulk additions.
If a resync stalls or CPU stays pinned afterward, delete the local index cache and let it rebuild. On macOS it lives at ~/Library/Application Support/Cursor/Index/; quit Cursor, remove that folder, reopen.
Step 4: Give important files semantic names
Split utils.ts into parseInvoice.ts / formatCurrency.ts / validateEmail.ts. The retrieval score combines the filename signal and the content signal, so a descriptive name jumps straight to the top.
Step 5: Pin canonical files via a project rule
Add a project rule (.cursor/rules/*.mdc, the current format; legacy .cursorrules at repo root still works) that tells the Agent which files to always read:
When working on invoice logic, always read:
- src/utils/parseInvoice.ts
- src/types/invoice.ts
- src/api/invoices.ts
These define the canonical model and parser.Cursor feeds matching rules straight to the model — effectively a hand-built index for that workflow.
Step 6: Evict noise from the panel
Each item in the context panel has an × to remove it. Drop unrelated tabs and history items to free window space for the target. In Agent/Composer settings you can also turn off “Auto-include open tabs.”
How to confirm it’s fixed
- Re-run the same prompt and confirm the target file now appears in the context panel.
- After the response, ask “List every file you read for this answer” and check the target file is named.
- Pull the repo on a second machine and reproduce — confirms you fixed the shared config (ignore rules, filenames, project rule), not just your local index.
If it still fails
- Reduce the prompt to one keyword plus an explicit
@File, to isolate retrieval from prompt ambiguity. - Roll back the most recent
.cursorignorechange or Cursor upgrade. - Capture the indexing log: View → Output → select “Cursor” / indexing channel from the dropdown.
- Search forum.cursor.com for “context panel missing”; if you file a report, include version, repo structure, and the missing file’s path.
Prevention
- Use semantic filenames for important files; avoid
utils.ts/helpers.ts. - Keep
.cursorignoreto truly off-limits files (secrets, vendored junk). For “don’t search it but I might@it,” use.cursorindexingignoreinstead. - Pin canonical files for core workflows in a
.cursor/rulesfile or aCONTEXT.md. - After bulk renames or additions, immediately Cmd+Shift+P → “Cursor: Resync Index” — don’t wait for the polling cycle.
- For high-stakes prompts, manually
@-attach the key references. Don’t bet on auto-retrieval.
FAQ
Why does @filename do nothing for one specific file?
That file is matched by .cursorignore, which blocks @-mentions too (as of June 2026). Remove or narrow the rule, or switch it to .cursorindexingignore if you only meant to keep it out of search.
How long until a new file shows up automatically? Cursor auto-resyncs changed files on a polling cycle of a few minutes (roughly every 5-10 min) using a Merkle-tree diff. Save the file first, then run “Cursor: Resync Index” if you don’t want to wait.
Where do I check indexing status now? Cursor Settings → Indexing shows sync status and the indexed file count; Indexing & Docs → “View included files” lists exactly which paths made it in. (Older builds nested this under Settings → Features → Codebase Indexing.)
Does Cmd+K use the index at all?
No. Cmd+K (inline edit) operates on the current file and your selection. Repo-wide retrieval only runs in chat, Composer, and Agent. A repo file “missing” from a Cmd+K edit is expected — attach it with @ or use the Agent.
.cursorignore vs .cursorindexingignore — which do I want?
.cursorignore = full block (no search, no Tab, no Agent, no @). .cursorindexingignore = out of the search index only; still reachable by @ and the Agent. Use the indexing-ignore variant for large generated directories you occasionally reference.