#21695: fix(edit): include line numbers in duplicate match errors
agents
size: M
Cluster:
Tool Execution and Error Handling
## Summary
Enhances the edit tool error message to include line numbers when multiple occurrences of `oldText` are found, enabling agents to recover by reading the relevant lines and expanding `oldText` with surrounding context.
## Problem
When the `edit` tool finds more than one occurrence of `old_string`, it returns:
```
Found 2 occurrences of the text in <file>. The text must be unique. Please provide more context to make it unique.
```
This is correct behavior — ambiguous edits should be rejected. However, the error gives the agent **no actionable information** to recover with. The agent knows it needs more context, but doesn't know *where* in the file the duplicates are, so it can't easily construct a larger unique `old_string`.
In practice, agents (Codex, Claude Code) tend to **give up and stop** rather than retry with expanded context, because the retry requires reading the whole file and manually finding surrounding lines.
## Changes
The error message now includes the **line numbers** where the duplicate matches were found:
```
Found 2 occurrences of the text in <file> (lines 284, 292). The text must be unique. Please provide more context to make it unique.
```
With line numbers, an agent can:
1. Immediately read only the relevant lines
2. Expand `old_string` to include the surrounding function signature (which is unique)
3. Retry the edit successfully — without reading the entire file
## Implementation
- Added `wrapEditToolWithLineNumbers` wrapper function in `src/agents/pi-tools.read.ts`
- Intercepts "Found X occurrences" errors from the base edit tool
- Reads the file and finds all line numbers where `oldText` appears (supports multi-line text)
- Enhances the error message with line numbers (truncates to first 5 if more than 5 total)
- Falls back to original error if enhancement fails
## Tests
Added `src/agents/pi-tools.read.edit-line-numbers.test.ts` with test cases:
- Single-line duplicate text
- Multi-line duplicate text
- Many occurrences (truncation test)
- Unique text (normal operation)
All tests pass ✅
Fixes #21645
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR enhances the edit tool error messaging by adding line numbers when duplicate text matches are found. When an edit operation fails due to multiple occurrences of `oldText`, the error now includes line numbers (e.g., "Found 2 occurrences... (lines 3, 5)") instead of just the count. This enables agents to immediately identify where duplicates exist and expand `oldText` with surrounding context to make it unique.
The implementation uses a wrapper function that intercepts duplicate match errors, reads the file to find all occurrence line numbers, and reconstructs the error message with this additional context. The wrapper handles multi-line text correctly and truncates to show only the first 5 line numbers if there are more than 5 occurrences.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge - it's a non-breaking enhancement with solid test coverage
- The change is well-isolated (wrapper pattern), thoroughly tested with 4 test cases covering single-line, multi-line, truncation, and normal operation scenarios. The error handling is defensive with fallback to original error if enhancement fails. No breaking changes to existing functionality.
- No files require special attention
<sub>Last reviewed commit: 6ec8597</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#18466: fix: suppress recoverable mutating tool errors when agent already r...
by stijnhoste · 2026-02-16
74.5%
#22087: Preserve assistant reply when exec fails under suppressToolErrors
by graysurf · 2026-02-20
74.0%
#12487: fix(agents): strip orphaned tool_result when tool_use is sanitized ...
by skylarkoo7 · 2026-02-09
73.9%
#10189: fix: resolve file_path param in tool display for read/write tools
by Yida-Dev · 2026-02-06
73.7%
#23381: fix(tools): allow empty newText in edit tool for text deletion
by SidQin-cyber · 2026-02-22
73.4%
#19125: fix(edit): allow empty string newText for line deletion
by aldoeliacim · 2026-02-17
73.4%
#19113: fix: prevent duplicated text after tag stripping
by Clawborn · 2026-02-17
73.4%
#9861: fix(agents): re-run tool_use/tool_result repair after limitHistoryT...
by CyberSinister · 2026-02-05
72.8%
#13282: fix(agents): instruct agent not to retry lost tool results
by thebtf · 2026-02-10
72.7%
#8345: fix: prevent synthetic error repair from creating tool_result for d...
by vishaltandale00 · 2026-02-03
72.7%