APP-4882 - fix misleading oversized-file read error — subagent
APP-4882 - fix misleading oversized-file read error is a Claude Code subagent that gives large-file read failures the right reason. It applies to read_files, get_files, and search_codebase.
AGPL-3.0 ★ 720 updated 2026-11-10
.claude/agents/APP-4882---fix-misleading-oversized-file-read-error.mdWhat APP-4882 - fix misleading oversized-file read error does
This subagent separates local file-read failures by cause. Missing paths, files above the 1 MB limit, and image-processing failures receive different messages, while an oversized file report includes both its size and the allowed limit.
The change uses describe_failed_files across read_files, get_files, and search_codebase, so mixed batches keep one path-specific reason per failure. Partial success remains intact, and the remote proto path receives the same message. Successful reads, truncation, and byte budgeting stay unchanged.
What it helps with
- report why an existing file above 1 MB could not be read
- separate missing paths from image-processing failures
- show every failure reason in a mixed file batch
- keep error text consistent across three file-reading tools
Example prompts for the agent
- Use the APP-4882 - fix misleading oversized-file read error subagent to fix the misleading error for an oversized file.
- Update
read_files,get_files, andsearch_codebaseso each failed path shows its own reason. - Split
BinaryFileReadResultfailure cases without changing successful reads or the 1 MB limit.
How to install APP-4882 - fix misleading oversized-file read error
Manually: put the files in place
.claude/agents/APP-4882---fix-misleading-oversized-file-read-error.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/APP-4882---fix-misleading-oversized-file-read-error.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/APP-4882---fix-misleading-oversized-file-read-error.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about APP-4882 - fix misleading oversized-file read error
How do I install APP-4882 - fix misleading oversized-file read error in Claude Code?
Add .claude/agents/APP-4882---fix-misleading-oversized-file-read-error.md to the Claude Code agents directory.
What does APP-4882 - fix misleading oversized-file read error do?
It replaces the generic missing-file result with separate reasons for a missing path, an oversized file, and an image-processing failure. The same reason format is used by the three file-reading tools.
How does APP-4882 handle a file above the size limit?
An existing file above 1 MB is reported with its size and the permitted limit. The reason is stored separately from the path, so the combined message does not repeat the filename.