Why your AI agent edits the wrong file — three causes and how to check each

You know the feeling. You ask it to fix the label on a button. The agent cheerfully reports: done, edited. You open the app — same button. You open the file — same code.

The agent didn't lie. It honestly edited a file. Just not that one.

Good news: there are only three reasons this happens, and each takes a minute to check. Start with the most common.

Cause 1: it's working in a different folder

The agent edits src/ui/Button.tsx. You're looking at your src/ui/Button.tsx. The paths match and the files differ — because your roots differ.

This happens more than you'd think: the agent was started from a subfolder or another directory; you opened a second clone for an experiment; or you're using a git worktree and the agent sits in the neighbouring tree, on a different branch.

How to check. Ask it where it is and which branch it's on:

pwd && git branch --show-current

Compare that with what's open in your editor. And insist on absolute paths in its reports — /home/me/shop/src/ui/Button.tsx, not "edited Button.tsx". Half of these mysteries unravel on that line alone.

How to fix. Start the agent from the project root. If several are running at once, give each its own folder rather than sharing one. And check the branch before editing: the file can be right while the branch is not the one you build from.

Cause 2: there's a twin file in the project

Second most common, and the sneakiest. Your repository holds two files with the same name:

• src/components/Button.tsx and src/legacy/Button.tsx;
• a copy of a page left over from a refactor;
• utils.ts in four places;
• a component and its "old version" nobody deleted.

The agent searches by name, finds the first match, and confidently edits it. Same logic you'd use searching in your editor: the name matches, so it must be the one.

How to check. Find every match at once:

git ls-files | grep -i button

More than one line? You've found your cause. Next, work out which file actually ships: look at what gets imported where the button is rendered.

How to fix. Put the exact path in your request: not "fix the button" but "fix src/components/Button.tsx". Delete dead copies — they confuse humans too. If the old code must stay for now, say so in your project rules: "never touch files under src/legacy/".

Cause 3: it's editing a generated file

Here the edit really does land in the file you're looking at — and still vanishes. Because that file isn't written by a human; it's produced by a build.

Usual victims: everything under dist/, build/, out/; compiled CSS; an API client generated from a schema; project configs produced by a generator. You see the change, you run the build, and the file is overwritten with the original.

How to check. Two quick tells: the file is listed in .gitignore (so it's a product, not a source), and its header says something like "autogenerated — do not edit".

How to fix. Edit the source: the template, the schema, the generator config — whatever the file is built from. And tell the agent outright: "don't touch dist/, that's build output." It won't feel that boundary on its own — to it, text is text.

A one-minute checklist

Before you argue with the agent, run top to bottom:

1. Is it in the same folder and on the same branch as you?
2. Is there exactly one file with that name in the project?
3. Is that file a source or a build result?
4. Did you restart the server or rebuild after the edit?

Three cases out of four close right here. The rest is ordinary debugging with AI.

Why doesn't the agent catch this itself?

Because it sees a filesystem, not your intentions. A file with a matching name exists, it has write permission, the edit applied — from its point of view the job is done. It has no idea a different directory is open in your editor. This is one of the structural sources of bugs in AI-written code: a formally correct action in the wrong place.

How do I stop this happening again?

Build two habits. First: ask for absolute paths of every changed file — then the mistake is visible immediately, not half an hour later. Second: end an edit with a check, not a report — "show me what changed" or git diff. The report misleads you not because the agent is sly, but because it reports its action, not your result.

It says "file not found" when the file is right there

Same cause number one, from the other side: the agent is looking from a different root. Give it the full absolute path and the "missing" file turns up instantly.