Why does Claude Code's Edit tool reject an edit whose old_string looks right, and what makes the retry succeed?
answer
- string replacement, not regex
- match must be character-exact
- exactly one occurrence
- longer context or replace_all
- read-before-edit rules changed in 2.1.208
basics
~20 sEdit is exact string replacement: old_string must match the file character for character, including whitespace, and occur exactly once. A retry succeeds after re-reading the file, copying the text exactly, and adding surrounding lines or setting replace_all for repeats.
solid answer
~40 sThe `Edit` tool replaces `old_string` with `new_string`; it does no regex or fuzzy matching. Three checks must pass. **Read-before-edit**: Claude must have read the file in the conversation (a `PARTIAL view` read doesn't count); since v2.1.208 newer models can skip it when reading wouldn't need a prompt, while Opus 4.6, Haiku 4.5 and older always need it. **Match**: one character of whitespace or indentation difference misses. **Uniqueness**: if the string occurs more than once, Claude must widen it with surrounding context or set `replace_all: true`. The usual causes are tabs against spaces, text recalled instead of copied from the read, a duplicated line, or a file a formatter rewrote. A file changed on disk still edits if `old_string` matches the current content exactly once; otherwise Claude re-reads it first.
code
json · 6 lines{
"file_path": "/repo/src/config/loader.ts",
"old_string": " const retries = 3;\n const timeoutMs = 5000;",
"new_string": " const retries = 5;\n const timeoutMs = 5000;",
"replace_all": false
}go deeper
Remember that Edit is an exact find-and-replace: the old text must match character for character and appear once, so a failed edit usually means the text or its whitespace differs.
Explain the three checks, read-before-edit, exact match and uniqueness, and how a longer old_string or replace_all resolves a duplicate match.
Diagnose failed edits from a transcript: formatter churn, tabs against spaces, recalled text, partial reads, and know which behaviour changed in 2.1.208 and 2.1.228 and which models still require the read.
Weigh why an exact-match edit tool is preferable to whole-file rewrites for review and safety, and what workflow choices, such as formatter timing, reduce wasted retries across a team.
## What the Edit tool actually does Claude Code's `Edit` tool performs **exact string replacement**. Its input names a `file_path`, an `old_string` and a `new_string`, plus an optional `replace_all` flag. It replaces the first string with the second. It does **not** use regular expressions and does **not** fall back to fuzzy matching, so a string that is "nearly" right is simply wrong. Its siblings handle the other cases: `Write` creates a file or overwrites one with full content (it doesn't append or merge), and `NotebookEdit` changes Jupyter notebook cells by `cell_id`. For a partial change to an existing file, Claude uses `Edit`. ## The checks every edit must pass Before anything else, a path matched by a `Read` deny rule is refused, including creating a new file there (v2.1.208 or later). Then three checks apply: 1. **Read-before-edit.** Claude reads the file in the current conversation before editing it. A read cut short with a `PARTIAL view` notice doesn't count. Claude Opus 4.6, Claude Haiku 4.5 and older models always require the read; newer models can edit an unread file when reading it wouldn't need a permission prompt and the `Read` tool is available. 2. **Match.** `old_string` must appear in the file exactly as written. One character of whitespace or indentation difference is enough to miss. 3. **Uniqueness.** `old_string` must appear exactly once. When it appears more than once, Claude either supplies a longer string with enough context to pin down one occurrence, or sets `replace_all: true` to replace them all. Viewing a file through `Bash` also satisfies read-before-edit when the command is `cat`, `nl`, `bat`, `batcat`, `head`, `tail`, `sed -n 'X,Yp'`, `grep`, `egrep`, `fgrep` or `rg` on a single file with no pipes or redirects. That affects edit eligibility only, not permissions. ## Files that changed after the read A formatter, a code generator or you in your editor can rewrite a file between Claude's read and its edit. Since v2.1.208, such a file can still be edited when `old_string` matches the **current** content exactly and unambiguously and Claude Code can read the file without prompting; the result notes that the file carries other changes, so Claude re-reads it before edits that depend on surrounding content. In any other case, such as a stale `old_string`, Claude reads the file again. Before v2.1.208, Claude Code refused any edit to an unread file or one changed on disk after the read. ## Why a correct-looking edit fails - **Indentation.** Tabs against spaces, or a different indent depth, break the match. - **Trailing or inner whitespace.** Invisible in a transcript, fatal to an exact match. - **Recalled text.** A snippet written from memory of the code rather than copied from the read. - **Duplicates.** A repeated import, log line or closing block matches twice, so the uniqueness check fails. - **Stale content.** A formatter changed the lines after the read, so the old text no longer exists. - **A blocked path.** A `Read` deny rule refuses the edit before matching starts. ## How the retry succeeds | Failure | What fixes it | | :- | :- | | No match | Re-read the file and copy the exact lines, whitespace included | | More than one match | Add surrounding lines until the string is unique, or set `replace_all: true` when every copy should change | | File changed on disk | Re-read, then build `old_string` from the current content | | Unread file on an older model | Read it first; a partial read must be completed | Reading a failed edit in a transcript is therefore mostly a matter of asking which of the three checks failed. A model that keeps retrying the same string is not going to succeed; the string has to change, or the file has to be read again. ## Write is not a workaround Switching to `Write` replaces the **whole** file with whatever content Claude supplies. Since v2.1.228, newer models can overwrite an existing file they never read under the same conditions as read-before-edit, while notebooks and partially read files always need the read; older models always need it. Using `Write` to dodge a matching problem risks dropping every change Claude didn't reproduce in full.
- When should Claude Code's Edit use replace_all instead of a longer old_string?Use `replace_all: true` when every occurrence should change, such as renaming a local identifier used throughout one file. Use a longer `old_string` when only one occurrence should change and the others must stay. Setting `replace_all` to silence a uniqueness failure risks changing copies you never meant to touch.
- Why does a Claude Code edit fail after a formatter runs on save, and why does it sometimes still apply?The formatter can change whitespace or line breaks, so the `old_string` built from the earlier read no longer exists. Since v2.1.208 the edit still applies when `old_string` matches the current content exactly once and the file can be read without a prompt; otherwise Claude must read the file again.
Edit behaves like a find-and-replace that refuses to run unless the search text occurs exactly once, character for character. When it refuses, you don't loosen the search; you copy the text exactly, add enough surrounding text to make it unique, or explicitly choose to replace every occurrence.
- Edit tolerates small whitespace differences, so close enough will match.
- old_string accepts regular expressions for matching several variants.
- When old_string matches twice, Edit replaces the first occurrence.
- Switching to Write is a safe fix for any Edit that keeps failing.
- Every model can edit a file it has never read in the conversation.
Assumes Claude Code 2.1.286: edits to unread or changed files relaxed in 2.1.208 for newer models, and Write's overwrite rule in 2.1.228.