Claude Text Editor Tool — File Not Found
Claude's text_editor_20250124 tool call fails because the path doesn't exist, uses relative paths, or escapes the sandbox. Return descriptive errors (with the path Claude tried) so it can self-correct — a bare "file not found" causes retry loops.
Implement all six commands (view, create, str_replace, insert, undo_edit). Always resolve paths to absolute paths within an allowed sandbox root. Reject path traversal (../). Return errors as strings that describe both what went wrong and what alternatives exist ("File not found: /work/foo.py. Similar files: foo.js, foo.md").
The Error Symptoms
FileNotFoundError: [Errno 2] No such file or directory: 'src/main.py' → Relative path; Claude assumed CWD was project root PermissionError: [Errno 13] Permission denied → Path outside allowed sandbox; or file owned by another user IsADirectoryError: [Errno 21] Is a directory → Claude tried to view /home/user (dir); view returns listing Claude retries the same failing path 5 times → Error message didn't guide correction; add path suggestions str_replace error: "old_str appears 3 times, must be unique" → Common Claude mistake; return count + surrounding context undo_edit fails: "No previous edit to undo" → Undo stack not implemented; return proper error
The text_editor Tool Contract
Claude's text_editor_20250124 tool supports these commands. Your implementation must handle each:
| Command | Inputs | Behavior |
|---|---|---|
view | path, view_range? | Show file with line numbers, or dir listing |
create | path, file_text | Create new file with content (fail if exists) |
str_replace | path, old_str, new_str | Unique replacement of exact string |
insert | path, insert_line, new_str | Insert after line N (1-indexed; 0 = start) |
undo_edit | path | Undo last edit to this file |
What Actually Causes This Error
Fixes That Work (Tested Nov 2026)
1Sandbox Path Resolution
2Complete text_editor Implementation
3Provide Sandbox Location in System Prompt
Include in your system prompt: "Your working directory is /workspace/. All file paths should be under /workspace/ (absolute paths preferred). The current project is at /workspace/my-project/." This dramatically reduces relative-path guessing errors.
Preventing This Error Going Forward
- Always resolve to absolute paths. Relative → sandbox_root / relative.
- Reject path traversal explicitly. Test
resolved.relative_to(SANDBOX_ROOT). - Suggest alternatives in errors.
difflib.get_close_matchesis your friend. - Include sandbox location in system prompt. Reduces relative-path errors 80%.
- Auto-create parent dirs on
create. Reduces multi-step file creation. - Track edit history per file. Real
undo_editsupport. - Return descriptive errors, not raw exceptions. Claude self-corrects from good messages.
Researcher · AI Error Hub
Frequently Asked Questions
Anthropic's tool schema includes it, so Claude may call it. Even a stub that returns "undo not supported in this environment" is fine — just don't crash. If you skip it, Claude may retry more edits than needed, wasting tokens.
Yes. Claude uses line numbers to reason about insert operations. The reference implementation returns them in NNNNNN\ttext format (6-digit right-aligned + tab). Consistent formatting helps Claude parse.
Yes. For view, cap at ~50KB — long files should be viewed in ranges. Return "File too large (X bytes); use view_range to see sections." For create, cap at ~500KB. For edits on massive files, refuse and suggest smaller operations.
Path.resolve() follows symlinks. If the resolved target is outside sandbox, reject. Safer than allowing symlinks. If you need symlinks (rare), audit each carefully.
Not usually needed — Claude edits sequentially, one call at a time. If your executor is concurrent (parallel agents), use file locks. Simplest: mutex per-path.
Related Errors
Build Better Coding Agents
Weekly deep dives on file operations, sandboxing, and Claude Code patterns. 12,000+ developers subscribe.
Subscribe Free →