Blog
7 min read

Claude Code "Error Editing File": Why Edits Fail and How to Fix Them

Claude Code error editing file or writing file? The Edit tool needs an exact, unique match against the current file. The usual causes and how to fix them.

When Claude Code reports an error editing or writing a file, the cause is almost always that the text it tried to replace didn't match the file exactly once. Either the file changed underneath it (a formatter, your editor, a git checkout), the snippet differs by whitespace, or the snippet appears more than once. Less often, the path is blocked by your permission settings, sits outside the folders Claude is allowed to write to, or the file itself can't be written.

Usually Claude just re-reads the file and retries. This guide is for when it keeps failing.

Details reflect Claude Code as of November 2026, based on Anthropic's tools reference and error reference.

How the Edit tool works

Claude doesn't rewrite a whole file to change one line. It calls the Edit tool with two strings: old_string (the text to find) and new_string (what to put there). According to the docs, it's an exact string replacement, with no regex and no fuzzy matching.

For an edit to apply, these checks have to pass:

  1. The file was read first. Claude needs to have read the file in the current conversation. A read that was cut short (a file too large to read in one go) doesn't count. Older models such as Claude Opus 4.6 and Haiku 4.5 always require the read; newer models can skip it when reading the file wouldn't need a permission prompt.
  2. old_string matches exactly. The docs are blunt: "A single character of whitespace or indentation difference is enough to miss."
  3. old_string appears exactly once. If it appears twice, Claude has to include more surrounding lines to pin down one spot, or set replace_all to change every occurrence.

There's also a check that comes before all of these: if the path matches a Read deny rule in your permissions, the edit is refused outright, even for a brand-new file.

The Write tool is different. It replaces a whole file (or creates a new one). It has a similar read-first rule for existing files, but no matching step.

The common causes, and what to do

1. The file changed after Claude read it

This is the most common one. Claude read app.ts five minutes ago, and since then:

  • a formatter or linter (Prettier, Black, ESLint --fix, a format-on-save setting in your editor) reformatted it,
  • you edited it yourself,
  • a git pull, git checkout or git stash changed it,
  • a dev server or code generator rewrote it.

Claude's copy is now stale, so the old_string it builds from memory no longer exists in the file.

Current versions handle this better than they used to. If the file changed but old_string still matches the current content exactly and once, the edit goes through and Claude is told the file has other changes. If it doesn't match, Claude reads the file again before retrying.

What to do:

  • Usually nothing. Let Claude re-read and retry.
  • If it loops, tell it directly: "Re-read src/app.ts before editing it."
  • If a formatter runs on every save, avoid typing in a file while Claude is editing it. If you run a formatter from a Claude Code hook after each edit, expect Claude to re-read the file more often; that's normal.

2. Whitespace and invisible differences

The snippet looks identical on screen but isn't. Typical culprits:

  • tabs in the file, spaces in old_string (or the reverse),
  • different indentation depth,
  • trailing spaces at the end of a line,
  • Windows line endings (CRLF) versus Unix ones (LF),
  • non-breaking spaces or other invisible characters pasted in from a web page or chat.

What to do:

  • Ask Claude to re-read the exact lines it wants to change and copy them from the read output, not from memory.
  • Check the file's line endings. In VS Code, the status bar shows LF or CRLF; on the command line, file src/app.ts reports "with CRLF line terminators" when they're Windows-style. If a repo mixes both, fix that once with a .gitattributes file (see LF will be replaced by CRLF).
  • Run your formatter once yourself so the file is in a stable state, then let Claude continue.

3. The text appears more than once

Claude wants to change return null;, and the file has six of them. The edit is ambiguous, so it's refused.

What to do: nothing in most cases. Claude adds surrounding lines (the function name, the line above) until the match is unique, or uses replace_all when you actually want every occurrence changed. If you meant only one, say which: "only the return null in getUser."

4. The file is blocked by your permissions

If a Read deny rule covers the path, Claude Code refuses Edit and Write there. The docs give the message as:

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

(For Write it ends "and cannot be written".)

This is often deliberate: people deny reads of .env files and secrets folders. If you want Claude to edit that file, narrow the deny rule in .claude/settings.json or ~/.claude/settings.json. If you want it left alone, keep the rule. See Claude Code settings explained for where rules live.

5. The path is outside the working directory

By default Claude can work on files in the folder where you started claude. Paths elsewhere need approval, and if the setting permissions.blockWritesOutsideWorkingDirectories is on, Write and Edit refuse them in every permission mode. The refusal tells you to add the directory.

What to do:

  • Run /add-dir ../shared-lib during the session, or start with claude --add-dir ../shared-lib.
  • To keep a directory available in every session, list it under permissions.additionalDirectories in your settings.
  • If you meant to work in a different project, run /cd <path> or restart claude from that folder.

Claude Code's own settings files (like ~/.claude/settings.json) are a special case: when that block setting is on, adding the directory doesn't help, and you edit them yourself.

6. The file can't be written at the operating-system level

Sometimes the matching is fine and the disk says no:

  • the file or folder is read-only, or owned by another user (often after something ran with sudo),
  • the file is locked by another program (common on Windows),
  • the disk is full,
  • on macOS, your terminal app isn't allowed into ~/Desktop, ~/Documents or ~/Downloads.

What to do:

ls -l src/app.ts          # who owns it, and is it writable?
df -h .                   # is the disk full?

If the owner is root because a command ran with sudo, give the file back to yourself with sudo chown "$USER" src/app.ts (or add -R and a directory to fix a whole tree; check the path carefully first). Linux file permissions and chmod covers the details. On macOS, enable the folder for your terminal under System Settings > Privacy & Security > Files and Folders.

If you use Perforce, the docs describe a CLAUDE_CODE_PERFORCE_MODE=1 setting that makes Edit and Write refuse read-only files and tell Claude to run p4 edit first.

7. The file isn't UTF-8

Edit saves the whole file back as UTF-8, so it refuses files in older encodings such as Windows-1252 or Shift-JIS, binary files, and UTF-8 with invalid bytes, rather than garbling them. The message starts with File is not valid UTF-8. Claude will usually switch to a shell command that keeps the encoding, or ask you whether to convert the file. Converting once (for example with iconv) is usually the cleaner long-term fix, but check that nothing else depends on the old encoding first.

When Claude keeps failing in a loop

If the same edit fails three or four times:

  1. Stop it with Esc.
  2. Check the file yourself. Open it and look at the lines in question. Is there a formatter fighting Claude? Uncommitted changes from another tool?
  3. Give a precise instruction: "Read lines 40-80 of src/app.ts, then change the timeout from 30 to 60 in fetchUser."
  4. If the conversation is long and confused, commit what works and start fresh. A clean context often fixes what retries can't. See /compact vs /clear.

For problems that aren't about file edits (login, network, slow sessions), see Claude Code not working.

EasySpawn runs Claude Code on a persistent cloud server where the working directory, file ownership and tooling stay the same between sessions, which rules out a few of the causes above. See how it works or join the waitlist.

Related: Claude Code Hooks: Rules the Agent Can't Forget · "LF Will Be Replaced by CRLF": What the Git Warning Means and How to Fix It · Claude Code Settings Explained: settings.json Scopes, Precedence, and a Team Setup · Linux File Permissions Explained: chmod 755, 644, and "Permission Denied"

Keep reading