The Edit tool requires the target text to be unique within the file. When the same string appears multiple times, Edit fails. The standard fallback: Read the full file, make the modification, and Write the entire file back.
Why Edit fails
Edit does exact string matching. If processPayment appears on lines 15, 42, and 89, and you want to rename only the one on line 42, Edit can’t distinguish them. It fails with a “non-unique match” error.
The Read + Write fallback
- Read the complete file content
- Apply the modification to the correct location in the full content
- Write the entire modified file back
This bypasses the uniqueness requirement entirely. The agent has the full file content, can identify the correct location by surrounding context, and writes the complete updated file.
What doesn’t work
—force flag: doesn’t exist. The uniqueness requirement is a fundamental constraint, not an optional check.
Line numbers: Edit doesn’t accept line number parameters. It matches target text strings, not positions.
Regex: Edit does exact string matching, not regex. Increasingly specific patterns don’t change the matching behavior.
When to use Edit vs Read+Write
Edit — when the target text is unique within the file. Most single-line changes, adding new code, modifying unique function signatures. Simpler and more token-efficient than Read+Write.
Read+Write — when Edit fails (non-unique match), when making multiple changes throughout a file, or when the modification is complex enough that full-file control is easier.
One-liner: Edit requires unique text matches — when it fails (non-unique), use Read to load the full file, modify the content, and Write it back. No —force flag, no line numbers, no regex.