Agent file edit fails: 'old_string not found' / 'String to replace not found' or 'patch does not apply' / 'patch failed' because of whitespace, tabs or CRLF line endings. How do I fix it?

Cause: Exact-replacement edit tools and patches match text literally. Claude Code documents that its Edit tool does exact string replacement with no regex or fuzzy matching: old_string must appear in the file exactly as written (one whitespace or indentation difference is enough to miss), it must be unique, and the file must have been read first. Common triggers are tabs versus spaces, trailing spaces, CRLF line endings, text the agent remembered or retyped instead of copying, a file changed on disk since it was read, and a snippet that occurs more than once. git apply is similarly strict about context lines. Fix (best first): 1. Re-read the exact region just before editing and copy the text including indentation; don't rebuild it from memory. Include a few neighbouring lines so the match is unique, or use replace_all only when you really want every occurrence. 2. Check for invisible differences: cat -A file | sed -n '10,20p' shows tabs (^I) and CRLF (^M$). If the file uses CRLF, make the match include them or convert once deliberately (for example with a documented .gitattributes or editor setting) rather than mixed endings. 3. Check the file didn't change underneath you (formatters, another tool, git checkout) and re-read after any such action. 4. For patches: run git apply --check patch.diff first (a dry run). If context drifted only in whitespace, git apply --ignore-whitespace tolerates whitespace changes in context lines. git apply is atomic by default; --reject applies the hunks that fit and writes the rest to .rej files for manual handling; --3way tries a merge when blob ids are available. Regenerate the patch against the current file when many hunks fail. 5. Claude Code notes that Edit refuses files that are not valid UTF-8 (such as Windows-1252); use a shell command that keeps the encoding, or convert first. 6. If edits keep failing, have the agent write the whole file for small files, or make the change with a scripted, reviewed command. Don't: strip whitespace from the whole repository to make one edit match; it creates a noisy diff. Verify: git diff shows only the intended change, and the project's tests or linter pass. Sources: https://code.claude.com/docs/en/tools-reference https://git-scm.com/docs/git-apply