Agents · hallucination · measured July 2026 · 7 min
Your agent named a file with total confidence. The file doesn't exist.
You've seen it in Claude Code or Cursor: the agent references src/utils/auth.ts as if it's reading it off the screen, but there is no such file. It isn't lying. It's guessing. With no live view of your disk, a model fills the gap the only way it can: it predicts the most likely path from the millions of repositories it trained on, plausible for a typical project, wrong for yours. Here's the mechanism, and the one thing that ends it: letting the agent look instead of guess.
Start here
Why do AI agents hallucinate file paths?
A file-path hallucination is when an agent states a path (say src/utils/auth.ts) with complete confidence, and the file simply isn't there. It happens because a language model doesn't look at your disk; it predicts. Asked for a path it hasn't been handed, it generates the most probable one from the millions of repositories it trained on: a path that fits a typical project of your kind, but not the actual one on your machine. The tokens for a wrong path look exactly like the tokens for a right one, so it arrives with the same fluent certainty either way.
- 01A model doesn't read your filesystem: it predicts. Asked for a path it wasn't given, it invents the most probable one.
- 02"Most probable" means the average of every repo it trained on, so it reaches for the popular convention, not your actual layout.
- 03The wrong path is asserted as confidently as a right one: nothing in the output flags doubt. That's what makes it a hallucination.
- 04Each fabricated path is a failed round trip: the tool call errors 'file not found,' the agent guesses again: a wasted call and wasted tokens.
- 05The fix isn't a smarter model. It's grounding: one always-fresh, whole-machine index that returns the real path in ~85 µs, so it never guesses.
The picture
Two ways to produce a path. One looks inward. One looks at the disk.
The difference between a hallucination and a fact is where the answer comes from. On the left, the model consults its own prior (a slice of your project plus the average of everything it trained on) and predicts a path. On the right, it consults the one filesystem that's actually true: yours. Same question, opposite source.
Same request, two floors. On the left the model draws a path from its training prior and only learns it's wrong when the call fails. On the right it asks the real machine and gets the exact path the first time.
This is the least glamorous layer in the stack and the one every agent stands on, the backbone of the LLM economy. Get the source of the answer right, and the hallucination has nowhere to come from.
The tells · where the guess goes wrong
You can almost predict the wrong path.
Because the guess is drawn from the average of every project, the mistakes are patterned: the agent reaches for the popular convention instead of your actual one. A few you'll recognise, on the same kind of stack Claude Code and Cursor read every day:
| When the agent needs a path | What it guesses (wrong) | Why it lands there | What a grounded lookup returns |
|---|---|---|---|
| A Next.js API route | pages/api/user.ts | trained on years of the old router | src/app/api/user/route.ts |
| A shared helper | src/utils/helpers.ts | utils/ is the statistical default | src/lib/format.ts |
| The config | tailwind.config.js | the most common filename | tailwind.config.ts |
| A test file | __tests__/auth.test.ts | the convention it saw most | src/auth/auth.spec.ts |
| An env template | .env.example | nearly every public repo has one | none, you keep secrets elsewhere |
Illustrative patterns, not a benchmark: the exact wrong path depends on your project. The point is the mechanism: a plausible convention substituted for a fact. A grounded lookup returns the real path in the microsecond range on a 4.47-million-file machine, so the substitution never happens. See how an agent gets into this loop in how Claude Code finds files.
The cost of a guess
Every wrong path is a failed round trip.
The distance between guessing at a file and knowing where it is: six minutes of an agent grinding against a single blink.
Not all 71 of those tool calls were hallucinations, but they run on the same engine: guess a path or a location, run it, find out it was wrong, guess again. On a real 4.47-million-file machine that guess-and-verify grind took Claude Code 6 minutes and 57 seconds and about 58% of the session's tokens to open one file. Grounding collapses the whole loop into a single call. Measured on a Ryzen 9 9950X3D, 64 GB DDR5, NVMe, Windows 11, 4.47M files.
Why the model guesses
It was never looking at your disk. It was finishing a pattern.
- 01
It predicts, it doesn't look. A model writes a path the same way it writes a sentence, as the most probable next tokens. With no live view of your disk, “most probable” is the average of every repo it trained on, not the one in front of it.
- 02
Partial context invites extrapolation. It has seen a slice of your project (a few open files, a directory listing, the framework's conventions) and fills the rest from its prior. The more standard your stack, the more confident the guess, and the more it defaults to the popular layout instead of yours.
- 03
Confidence is uncalibrated. The wrong path arrives in exactly the same fluent, certain tone as a right one. Nothing in the output flags doubt, which is why it reads as a hallucination and not an obvious error you'd catch on sight.
- 04
The correction comes too late. The agent learns the path was wrong only when the tool call fails with 'file not found'. Then it guesses again. Every fabricated path is a failed round trip: a wasted call, wasted tokens, a few more seconds on the clock.
The fix isn't a stronger model: a stronger one guesses better but still can't see your disk. The fix is grounding: hand the model the real answer before it has to invent one. It's the same reason retrieval cuts factual hallucination in a RAG pipeline: replace the guess with a fact. But file paths raise the bar. The ground truth is your live filesystem: every repo, the config and the document, the 90% of the drive that was never in git, changing on every save. A repo-scoped index (the way Cursor keeps an embedding of the project you have open) grounds the guess inside that one folder, and still fabricates for the sibling repo or the file outside it. Grounding a whole machine takes a whole-machine index.
Replace the guess with a fact
Let the agent look. Then it can't make one up.
Interlinked keeps one always-fresh index of every file on the machine (names and contents) and hands it to any agent over MCP. Now where's the auth logic? is a lookup, not a guess: the agent calls once and gets back a path that exists, on your disk, right now, exact folder, exact line. No fabrication, no failed round trip, no retry loop. One signed installer wires the index into 19 AI clients at once, Claude Code and Cursor among them. It stays warm in the background at about 44 MB, and a file you just saved is searchable about a millisecond later, so the answer is never stale.
Everything local is free forever, on all your devices, no card. Hosting starts at $5.99/mo. Download for Windows →
Questions people actually ask
Hallucinated paths, in plain terms.
Why do AI agents hallucinate file paths?
Because a language model predicts a path instead of looking one up. When it needs a path it hasn't been given, it generates the most probable one from the millions of repositories it trained on: a path that fits a typical project of your kind, but not the actual one on your disk.
How do I stop my agent from making up file paths?
Ground it. Give the agent a tool that returns real paths from your actual machine, instantly, so it looks instead of guesses. When the true path is one fast lookup away, the model never has to invent one, and the failed-path retries disappear.
Do Claude Code and Cursor hallucinate file paths?
Any LLM-driven agent can. Cursor keeps an index of the repository you have open, which grounds guesses inside that project; both still fabricate paths for anything outside that boundary: a sibling repo, a config, a git-ignored file. A whole-machine index closes that gap.
Is a hallucinated file path the same as a bug?
No. A bug is code that runs incorrectly; a hallucinated path is asserted with full confidence and only fails when the tool call runs. That late, confident failure is what makes it costly: the agent burns a call and tokens discovering the path was never real.
Does a bigger or smarter model fix path hallucination?
Not the root cause. A stronger model guesses better, but it still can't see your disk, so it still guesses. The fix is retrieval (grounding the model in your real filesystem), not more parameters.
Let your agent look instead of guess.
Ground every agent on your machine in one always-fresh, whole-machine index. It stops inventing paths because it never has to: it asks, and the real one comes back in microseconds.
DOWNLOAD FOR WINDOWS →Free forever · No card · Hosting from $5.99/mo