# Atlas read tool: "File not found: " and how to fix it > To fix "File not found: " in Atlas, pick the correct name from the "Did you mean one of these?" list, or locate the file with glob and pass that exact path to read. Atlas returns "File not found: " because the read tool could not stat the file you asked for, and the fix is almost always to pick the correct name out of the "Did you mean one of these?" suggestion list that Atlas prints underneath the error. ReadTool.miss lists the target's parent directory and offers near-miss candidates before failing, so a typo produces a suggestion list rather than a bare error. If the suggestions do not help, use glob to locate the file by pattern, then confirm your working directory, because relative paths resolve against the instance directory and not against the shell you launched from. ## Symptom The read tool fails with: File not found: , sometimes followed by "Did you mean one of these?" and a list of similarly named files in the same directory. ## Cause ReadTool.miss lists the target's parent directory and offers near-miss candidates before failing, so a typo produces a suggestion list rather than a bare error. The path you passed does not exist as written, either because of a misspelling, a wrong relative base, or a permission rule that excludes it. ## Fix 1. Read the suggestion list in the error and pick the intended file. Atlas prints "Did you mean one of these?" with similarly named files from the same directory, and the correct target is usually right there. 2. Use glob to locate the file by pattern if the suggestions do not help. A pattern search across the project finds the real path when you only remember part of the name. 3. Check the working directory: relative paths resolve against the instance directory, not against the terminal you happened to launch Atlas from. 4. Confirm the file is not excluded by an external-directory permission rule. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs. 5. Re-run read with the exact path string that glob returned, rather than retyping it by hand. ## Why does Atlas report "File not found: " Atlas reports "File not found: " when the read tool cannot stat the target you named. ReadTool.miss then lists the parent directory and offers near-miss candidates, so a single typo in a 2026 Atlas session produces a "Did you mean one of these?" suggestion list instead of a bare failure. The error is a miss, not a crash. Atlas's read tool does not silently return empty content when a path is wrong, and it does not guess a substitute file on your behalf. Instead, ReadTool.miss enumerates the parent directory of the path you asked for and surfaces the entries whose names are close to what you typed. That behavior is deliberate: the most common reason a read fails is a one-character mistake in a filename, and the fastest correction is a list of the real names sitting next to it. If the parent directory itself does not exist, there are no near-miss candidates to show, and you get the bare "File not found: " line with no suggestion list. That distinction is a useful signal. A suggestion list means the directory is right and the filename is wrong. No suggestion list means the directory portion of your path is the part to question. ## How to fix "File not found" in the Atlas read tool Fix the Atlas "File not found" error in 4 steps: read the "Did you mean one of these?" suggestion list and pick the intended file, run glob to locate it by pattern, confirm the working directory because relative paths resolve against the instance directory, then check external-directory permission rules. Work the list in order, because it goes from cheapest to most involved. The suggestion list costs nothing to check and resolves the majority of these errors on the spot. When the suggestions do not contain your file, glob is the next tool: it matches by pattern, so you can search for a fragment of the name across the project and get back the real path. Once glob returns a path, copy that exact string into read rather than retyping it, since retyping is what produced the miss in the first place. Only after both of those fail should you start questioning the directory base or a permission rule. Be honest about the caveat here: glob searches by filename, so if the file genuinely does not exist under any name, no amount of pattern matching will conjure it. At that point the question is whether the file was ever created, not whether read can find it. ## Why relative paths break in Atlas sessions Relative paths in Atlas resolve against the instance directory, the 2nd most common source of "File not found: " after a simple typo. A path like src/index.ts can read cleanly in your terminal and still miss inside an Atlas session started from a different root. The mismatch is easy to miss because both paths look correct in isolation. If you started Atlas from a repository root and the file lives under a nested package, a relative path written from the package's point of view will not resolve. The reliable habit is to pass paths that you have seen Atlas itself produce. When glob returns a match, or when Atlas quotes a path back to you in a previous tool result, that string is already expressed in the form the read tool expects. Copying it forward removes the entire class of base-directory mistakes. If you are unsure which directory Atlas is anchored to, the quickest check is a glob for a file you know exists near the root: the path Atlas returns tells you exactly where it is standing. ## Can a permission rule cause "File not found" in Atlas Yes. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so an external-directory rule can stop read from reaching a path that exists on disk. Check your allow, ask, and deny configuration, the 3 rule kinds, before you conclude the path is wrong. The permission layer sits in front of the tool, not behind it, which means a denied path never reaches the filesystem call at all. That is the correct design for an agent that runs commands on your machine, but it does mean a file you can see in your editor may still be unreachable by the read tool. The tell is that the path is unambiguously correct, the directory exists, and glob either finds nothing or finds the file while read still refuses it. When you see that combination, the next thing to inspect is your allow, ask, and deny configuration rather than the path string. Widening a rule is a decision to make deliberately, since the whole point of the gate is that Atlas asks before touching things outside the space you granted it. ## How to verify the "File not found" fix worked Verify the Atlas read fix by re-running read on the corrected path. A successful call shows 2 signs: read returns file contents instead of "File not found: ", and the "Did you mean one of these?" suggestion list does not reappear on the second attempt. A clean verification has two parts. First, read returns content, which proves the path resolves and the permission rules allow it. Second, the suggestion list is gone, which proves you are no longer hitting the near-miss branch of ReadTool.miss. If the suggestion list returns with a different set of candidates, you have moved to a different directory and introduced a new typo rather than fixing the original one. A durable habit that prevents repeats: when you need a file more than once in a session, take the path from the first successful read and reuse it verbatim. Atlas snapshots file changes as git patches so edits can be diffed and rolled back, so once you are reading and editing the right file, a mistaken change is recoverable. A mistaken path, by contrast, just wastes a turn. ## FAQ ### what does File not found mean in Atlas It means the Atlas read tool could not stat the path you passed. Atlas prints "File not found: " and, when the parent directory exists, adds "Did you mean one of these?" with similarly named files from that directory. ### why does Atlas say Did you mean one of these ReadTool.miss lists the target's parent directory and offers near-miss candidates before failing, so a typo produces a suggestion list rather than a bare error. The file you actually wanted is usually one of the listed names. ### how do I find a file in Atlas when read cannot find it Use glob to locate the file by pattern. Glob matches on filename, so a partial name returns the real path, which you then pass to read verbatim rather than retyping. ### why does a relative path fail in Atlas but work in my terminal Relative paths in Atlas resolve against the instance directory, not against the shell you launched from. A path that is correct relative to your terminal can still miss inside the Atlas session. ### can Atlas permissions block the read tool from finding a file Yes. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so an external-directory rule can exclude a file that exists on disk. Confirm the file is not excluded before blaming the path. ### should I use glob or grep to find the file Atlas cannot read Use glob when you know part of the filename, since glob matches names by pattern. Grep searches inside file contents, so it is the wrong tool for locating a file whose path you got wrong. ### how do I confirm the Atlas File not found error is fixed Re-run read on the corrected path. A successful call returns the file contents and the "Did you mean one of these?" suggestion list does not reappear. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/read-file-not-found Source of truth: aeo_pages row `/resources/troubleshooting/read-file-not-found` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.