Cursor's agent doesn't know about a file that's clearly in your repo? Here's why

The file is right there in the explorer. You can open it, read it, edit it by hand. But ask Cursor’s agent a question about it — without pasting the code in yourself — and it either says something like “I don’t see that file in the codebase” or, worse, confidently describes code that isn’t what’s actually in the file. You didn’t imagine the file. Cursor just never looked at it.

If you searched “cursor doesn’t see my file,” “cursor agent missing context,” or “cursor hallucinating code that doesn’t exist,” this is that bug — and it’s not the model being careless. It’s the index the agent is actually reading from being smaller than your repo.

Why the agent can be “blind” to a file that’s obviously there

Cursor doesn’t hand your entire repository to the model on every request — for any codebase past a trivial size, that would be slow and expensive. Instead it builds a semantic index: it chunks and embeds your files ahead of time so the agent can pull in the relevant pieces on demand (this is what powers @codebase and a lot of the context the agent grabs on its own without you asking for a specific file).

The problem is that the index is deliberately — and silently — incomplete. Three things routinely fall outside it:

• Anything matched by .gitignore or .cursorignore. The indexer respects both, the same as it should, but it’s easy to forget a pattern is broad enough to catch a real source file — a .env-adjacent path, a folder named dist or build that also happens to hold hand-written code, or a rule copied from another project that doesn’t quite fit this one.
• Files past the indexing size ceiling. Large generated files, big fixture JSON, or minified bundles get skipped rather than choked on.
• Files the index hasn’t caught up to yet. A file you just created, renamed, or moved can exist on disk before the background indexer has embedded it, especially right after a big refactor.

When the agent answers from retrieval and the retrieval has nothing for that file, you get one of two failure modes: an honest “I don’t have that file” (harmless, just annoying), or the agent papering over the gap with a plausible guess based on similarly-named files elsewhere in the index (much worse, because it reads exactly as confident as a correct answer).

The three usual causes — and the fix for each

1. The file is excluded by an ignore pattern. Check whether it’s actually being excluded before assuming it’s a bug: run git check-ignore -v path/to/file in the repo (the -v flag shows you which rule in which file matched, git’s own ignore rules and Cursor’s .cursorignore follow the same syntax). If a rule is catching more than you intended — a broad *.config.* or a directory name that’s shared between build output and real source — narrow the pattern or add an explicit negation (!path/to/file) rather than deleting the whole rule.

2. The file is too large to index. This shows up most with big generated files, large seed/fixture data, or bundled output that ended up living next to source. If the agent needs to reason about a huge file, the index isn’t going to carry it — skip straight to the manual-attach move below instead of fighting the size limit.

3. The index is stale. Recently added, renamed, or moved files can lag behind. In Cursor Settings, under Indexing & Docs, you can see the indexing status for the workspace and trigger a resync rather than waiting for the background pass. Do this right after a large rename/move operation, not just when something looks wrong — it’s cheap and it rules the cause out immediately.

The one move that works regardless of index state

Don’t rely on the agent to find the file on its own — @-mention the exact file (or drag it into the chat) so its full current content is attached directly to your prompt. This bypasses semantic retrieval entirely: it doesn’t matter if the file is ignored, oversized, or freshly created, because you’re no longer depending on the index to have it. For any file you already know is relevant — especially the one you suspect is the problem — attaching it directly is both faster and more reliable than hoping the index picked it up.

How to confirm it’s actually fixed

1. After adjusting an ignore rule, re-run git check-ignore -v path/to/file and confirm it now returns nothing (no match = no longer ignored).
2. After a resync, give the indexer a minute to finish before re-testing — asking again mid-index just reproduces the same gap.
3. Re-ask the original question without manually attaching the file. If the agent now cites something specific and correct from that file — an actual function name, an actual line of logic — rather than a generic or vague answer, the index has it.
4. If you’re on a deadline and can’t wait on the index, don’t treat that as the bug being unfixed — @-mention the file directly for now, and verify the index separately once you have time. The two are different problems: one blocks you right now, the other blocks the agent from finding this file on its own next time.