Claude Code error editing file, and the String to replace not found line

Find your cause

Most failures here come from one of three checks: Claude has read the file, the text it means to replace is in the file exactly as written, and it appears once. The rest stop the edit before those checks run. Pick the cause that matches what you see.

• String to replace not found in file
• The file is indented with tabs
• The file changed after Claude read it
• The text appears more than once
• Claude's read was cut short
• The characters look the same and are not
• File is not valid UTF-8
• Error editing file
• Invalid regular expression
• What does not help

The rule the Edit tool follows

The Edit tool performs exact string replacement. It takes the text to find and the text to put in its place, and it does not use regex or fuzzy matching. Anthropic names three checks that must pass before an edit applies. Claude read the file in the current conversation, and a read cut short with a PARTIAL view notice does not count. The text to find appears in the file exactly as written, where a single character of whitespace or indentation difference is enough to miss. And it appears exactly once, which Claude handles by supplying a longer string with more surrounding context, or by replacing every occurrence.

Anthropic adds a qualifier to the first check: Claude Opus 4.6, Claude Haiku 4.5 and older models always require the read, while newer models can edit a file they have not read when reading it would need no permission prompt and the Read tool is available. A path matched by a Read deny rule is refused before any of the three checks run.

Most of the causes below are one of those checks failing, which is why the fixes are about the file and the text. The rest stop the edit before a match is even tried: an undecodable file, a blocked path, a permission rule that will not compile.

The three checks and the exact-match rule come from Anthropic's tools reference, read on October 26, 2026.

String to replace not found in file

String to replace not found in file.

Error: String to replace not found in file.

String not found in file

What it means. The tool could not find the text it was told to replace, so it stopped and wrote nothing. The long form is the one people paste, and it carries the Error: prefix in some versions. The short form is the wording Anthropic uses in its own changelog, and it is what the VS Code diff view reported before v2.1.267 fixed it on a file with Windows line endings.

If it fails once, let the next attempt happen before you change anything. Anthropic's tools reference says that when the text Claude holds is stale, or matches more than once without replace-all, Claude reads the file again before editing. The steps below are for the case where it keeps happening.

What to do

1. Ask Claude to read the file again, then retry the edit. A fresh read is what makes the anchor real when the old one was stale or came from a partial view.
2. Paste the lines you mean, or name the function or heading they sit in, so the string Claude builds is the one in the file.
3. For several changes in one file, ask for one at a time. Each edit rewrites the file, so a later anchor made from the earlier copy can be out of date.
4. If it still fails on the same spot, work down this page: tabs, a changed file, a repeated string, a short read, and invisible characters each have their own test below.

Anthropic's error reference has no entry for this line today. The behaviour behind it is documented in the tools reference. The short wording appears in the changelog entries for v2.1.267 and v2.1.277, and the long form is quoted from issue 26996, which is still open. All read on October 26, 2026.

The file is indented with tabs

When the same file fails again and again, check the indentation first. A tab and a run of spaces look the same in a read, and the check compares characters. Anthropic states the consequence plainly: a single character of whitespace or indentation difference is enough to miss. A file indented with tabs is the case to rule out.

Issue 11447, filed by d5ve on November 11, 2025, is open: it describes Claude Code failing on files indented with tabs. Issue 26996, filed by lukewilliamboswell on February 19, 2026, is open too, and describes the Edit tool converting tabs to spaces and then failing to match. Neither carries a maintainer reply.

What to do

1. Ask Claude to make that one change with a shell command instead of the Edit tool. A command writes the change without a text match to fail, which is the same route Anthropic's own message offers for a file the Edit tool cannot decode.
2. Ask Claude to read the exact lines it means to change, not the top of the file, and retry on that.
3. If the file is yours to change, save it with space indentation. That removes the mismatch for good, at the cost of a diff across the whole file.
4. Update to the current release and try again. Both reports above are still open, so treat an update as worth doing rather than as the fix.

The whitespace rule is on Anthropic's tools reference. The two reports are read on the issue pages themselves on October 26, 2026, where both are open.

The file changed after Claude read it

Claude Code keeps the copy of the file it read. If something else wrote to that file in between, the text Claude holds may no longer be in it. Anthropic handles this case: a file that changed on disk can still be edited when the string matches the current content exactly and unambiguously and Claude Code can read the file without prompting. In any other case, such as a stale string, Claude reads the file again before editing.

Before v2.1.208, released on July 14, 2026, an edit on a file modified after reading failed even when the target text still matched uniquely. Anthropic's own account of the read is in the workflows page: Claude reads files fresh on each tool call, so it sees edits you make in another application the next time it reads that file.

What to do

1. Ask Claude to read the file again and retry. That is the same step Anthropic describes, said out loud.
2. Save in your editor before you ask for a change. An unsaved buffer is not the copy Claude reads.
3. Update to v2.1.208 or later, where the changed-file case stops failing when the match is still unique.
4. If another session, a formatter, or a generator writes to the same file, expect this to repeat. The last section on this page covers that case.

The changed-file rule is on Anthropic's tools reference, the fresh-read sentence on the common workflows page, and the v2.1.208 fix in the changelog. All read on October 26, 2026.

The text appears more than once

The second check is uniqueness. When the string appears more than once, Claude either supplies a longer string with enough surrounding context to pin down one occurrence, or replaces every occurrence. A failure here means the longer string it built still did not match, so the cause is usually the same as above: a character that differs somewhere in the wider block it reached for.

What to do

1. Name the occurrence by what surrounds it: the function, the heading, the line above it.
2. If you want every occurrence changed, say so. Claude can replace all of them in one edit, which removes the uniqueness problem.
3. If the file holds a generated copy of the same lines, change the source and regenerate rather than editing the copy.

The uniqueness check is part of Anthropic's Edit tool behavior, read on October 26, 2026.

Claude's read was cut short

The first check is that Claude read the file in the current conversation, and a read cut short with a PARTIAL view notice does not count. A large file comes back one page at a time: one read returns at most 25,000 tokens by default, and a whole file over 256 KB is refused, so Claude reads a portion with offset and limit instead. On Claude Code v2.1.296 or later it can read the whole file, or a long line range, in one call by setting allow_large. Either way, a partial read leaves Claude holding the first page and not the rest.

Before v2.1.212, released on July 17, 2026, resuming a session could raise a false "File has not been read yet" error for a file that had been read with offset and limit.

What to do

1. Ask Claude to read the range it needs, for example the lines around the change, and edit inside that range.
2. Or ask it to search for the text first. Anthropic counts a cat, grep, rg, head, tail or sed -n view as a read for this rule, when the command ran on one file with no pipes or redirects and printed the file's text.
3. Update to v2.1.212 or later if the error appears right after you resume a session.

The partial-read rule and the page sizes are on Anthropic's Read tool behavior, the list of commands that count as a read on the same page, and the v2.1.212 fix in the changelog. Read on October 26, 2026.

The characters look the same and are not

A non-breaking space or a curly quote reads as its plain cousin and is a different byte. Exact matching sees the difference, and the failure looks identical to a wrong anchor. Anthropic fixed one of these on the writing side: before v2.1.47, released on February 18, 2026, the Edit tool silently turned curly quotes into straight quotes while making an edit.

A report of the reading side, issue 29869, described a file holding a non-breaking space and failing the same way. MatthiasRossbach filed it on March 1, 2026, and closed it himself to re-file it with the repository's template, so it is closed without a change.

What to do

1. Ask Claude to read the exact line and show what it actually contains before it edits, so the difference surfaces before the match is attempted.
2. Replace the whole line with the correct characters rather than matching the old one. A block you paste yourself carries the bytes you mean.
3. Update to v2.1.47 or later so a curly quote is not rewritten behind you. The match itself still needs the exact character.

The v2.1.47 fix is in Anthropic's changelog, and the non-breaking-space report is at issue 29869, closed by its author without a change and read on October 26, 2026.

File is not valid UTF-8

File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary.

What it means. Claude reached for the Edit tool on a file whose bytes do not decode as UTF-8, and Claude Code refused the change before writing anything. The tool saves the whole file back as UTF-8, which would replace every byte it cannot decode with the replacement character U+FFFD. A file that is meant to be UTF-8 gets the same refusal when it holds a single invalid byte sequence, because the check covers the file as a whole. The rest of the message says nothing was written and names the two ways forward.

Before v2.1.296, released on October 9, 2026, the edit applied and saved every undecodable byte as U+FFFD. That is a reason to update before you touch a file in a legacy encoding.

What to do

1. Keep the encoding and let Claude make the change with a shell command that reads and writes the file in that encoding, which is what the message tells it to do.
2. Or convert the file to UTF-8, or fix the invalid bytes in a file that should be UTF-8, and then ask for the edit again.
3. Update to v2.1.296 or later first if you have been editing legacy-encoded files on an older version, so you know whether that file has U+FFFD characters in it now.

The message, its causes and these steps are on Anthropic's error reference, and the UTF-8 rule for the tool is on the tools reference. Read on October 26, 2026.

Error editing file, and the cause behind it

Error editing file

File is covered by a Read deny rule in your permission settings and cannot be edited.

What it means. This line is short on purpose. Anthropic says that for a blocked file edit the conversation view shows only the short Error editing file line, and the full message appears in the transcript view, which you open with Ctrl+O. So the first step is reading the message you were not shown, because the line above the second block is one of several causes and the short line names none of them.

The documented blocks are a Read deny rule on the path, a path the worktree-isolation guard cannot resolve, and a path that names a network location. The deny rule is the one that looks like a match failure and is not: it stops the Edit and Write tools before any file access, including creating a new file at that path. Before v2.1.228 only the Edit tool was covered, and before v2.1.208 only an Edit deny rule blocked edits.

What to do

1. Press Ctrl+O and read the full message in the transcript. Everything below depends on which one it is.
2. For a deny rule, run /permissions and look for a Read or Edit rule on that path. Narrow or remove it in the settings file that holds it.
3. If the message says the path is spelled in a form that cannot be resolved, edit the file by its direct path, with no symlink or dot segment in it.
4. If it names a network location, work on a local copy. Isolation in a worktree does not lift that block.

The deny-rule message is on Anthropic's error reference, the short-line rule and the blocked-path causes are under Write or command blocked because the path cannot be safely resolved, and the network case has its own section. All read on October 26, 2026.

Invalid regular expression

Invalid regular expression: regular expression too large

What it means. Nothing on this page uses a regular expression, so this line is confusing in exactly the way it reads. Anthropic's changelog records two separate causes. Before v2.1.277, released on September 18, 2026, the Edit tool reported this line instead of String not found in file when a very large edit containing non-ASCII text did not match, so a plain failed match wore the wrong name. And before v2.1.260, released on September 3, 2026, one file permission rule with a pattern that would not compile, such as an unclosed bracket, made every file edit fail with Invalid regular expression.

What to do

1. Update to v2.1.277 or later if this appears on a large edit with non-ASCII text, so the next failure names itself correctly.
2. Run /permissions and look for a rule with an unclosed bracket or another malformed pattern. Fix the rule, and update to v2.1.260 or later so a broken rule guards only the path it spells.
3. If neither applies, treat it as a failed match and work through the causes above.

Both fixes are in Anthropic's changelog, under v2.1.260 and v2.1.277, read on October 26, 2026.

What does not help

• Reinstalling Claude Code. The program is running, and it rejected a text match. A reinstall changes nothing about the file or the string.
• A hook that repairs the edit. Anthropic says a call that fails tool-specific validation happens before hooks run, so it fires neither PreToolUse nor PostToolUseFailure. A hook can still replace a tool's arguments with updatedInput when it does run, which is not the same thing as rescuing a call that was already rejected. Issue 46001, filed by ZhouZijie77 on April 10, 2026, is closed as not planned: it reported that a PreToolUse hook on Edit was not invoked when the string did not match.
• Sending the same request again without a re-read. Claude reads the file again before editing a stale or ambiguous match, so a repeat that skips the read puts the same old string back in.

The rule about validation failures and hooks is under Anthropic's PostToolUseFailure event, and the report is at issue 46001, read on October 26, 2026. Its state there is closed as not planned.

When several sessions share one checkout

The changed-file cause is easy to rule out when one session is all that is running. With two or more sessions in the same folder it is the normal state: one session's edit is another session's stale anchor, and the failure lands in whichever one was mid-change. Omniscio is the desktop app we make for running many Claude Code sessions at once, and it can give a session its own copy of the project. Session isolation is off by default for Claude Code sessions, and it can be switched on for one session, for a project, or app-wide, so an isolated session works on its own branch and cannot overwrite the file another one is editing. The session isolation page covers where the switches live, and the guide to running several sessions covers the habits around them.

Sources

Every message and step on this page comes from one of these, each read on October 26, 2026.

• Tools reference, for exact string replacement, the three checks, read-before-edit, the commands that count as a read, the large-file limits and the non-UTF-8 refusal.
• Error reference, for the short Error editing file line and the transcript view, the UTF-8 refusal, the deny rule and the blocked paths.
• Changelog, for the release each fix shipped in: v2.1.47, v2.1.208, v2.1.212, v2.1.260, v2.1.267, v2.1.277 and v2.1.296, with v2.1.296 carrying the release date the page prints.
• Hooks reference, for where PreToolUse runs, what updatedInput can replace, and the rule that a validation failure happens before hooks run.
• Common workflows, for the sentence about reading a file fresh on each tool call.
• GitHub reports on anthropics/claude-code, each read on its own page: 3471 open, 11447 open, 26996 open, 29869 closed, 46001 closed as not planned.

Anthropic documents the Edit tool's behaviour on its tools reference, with the version notes in the changelog beside it. This page organises that material by the cause a reader can test on their own file, and it says where the reference is silent rather than filling the gap.

Common questions

Why does Claude Code say String to replace not found in file?

The Edit tool was told to replace a piece of text that it could not find in the file exactly as written. It performs exact string replacement, with no regex and no fuzzy matching, so one character of whitespace or indentation difference is enough to miss. Nothing was written, and asking Claude to read the file again and retry clears most of these.

What does Error editing file mean in Claude Code?

It is the short line the conversation view shows for a blocked file edit, and the cause is in the full message. Press Ctrl+O to open the transcript and read it. The documented causes include a Read deny rule on the path, a path the worktree-isolation guard cannot resolve, and a path on a network drive.

Why does the edit keep failing on the same file?

Usually because the file does not contain the characters Claude thinks it does. A file indented with tabs fails when Claude writes spaces, and there are two open reports of exactly that. Non-breaking spaces and curly quotes cause the same failure. Ask Claude to read the lines again, or have it make that change with a shell command instead of the Edit tool.

Does updating Claude Code fix the edit error?

Some causes, yes. Anthropic's changelog records fixes for a file changed after reading in v2.1.208, a spurious read error in v2.1.212, curly-quote corruption in v2.1.47, and two wrong-error cases in v2.1.260 and v2.1.277. The tab-indentation reports are still open, so updating is not the fix for those.

Can a hook fix a failed edit?

Anthropic says a call that fails tool-specific validation happens before hooks run, so it fires neither PreToolUse nor PostToolUseFailure. A hook can replace a tool's arguments with updatedInput when it does run, which is not the same as rescuing a call that was already rejected. A report asking for that was closed as not planned.

Is the file damaged when an edit fails?

No. Anthropic states the checks must pass before an edit applies, so a failed match writes nothing, and the refusal for a file that is not valid UTF-8 says in the message that nothing was written. The file is as it was, and the next attempt starts from the same content.