Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Read tool docs omit text fallback for files with image extensions but non-image contents

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
RAW_BUFFERClick to expand / collapse

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

Read tool behavior

Current Documentation

The docs currently say:

Read handles several file types beyond plain text:

  • Images: PNG, JPG, and other image formats are returned as visual content that Claude can see, not as raw bytes. Claude Code resizes and recompresses large images to fit the model's image size limits before sending them, so Claude may see a downscaled version of a large screenshot.

What's Wrong or Missing?

This section explains the normal image path, but it does not document the new v2.1.144 behavior for files whose extension looks like an image while the contents are actually text or other non-image data.

For example, if a file is named something.png but contains HTML, users now get a text fallback instead of an unrecoverable conversation. That behavior is useful and user-visible, but the docs do not explain it.

Without that note, users and SDK integrators can reasonably assume Claude Code decides solely from the filename extension and will always treat *.png as image input.

Suggested Improvement

Add a short note in the Read tool behavior section clarifying that Claude Code uses the file's actual contents when possible, not just the extension.

Suggested wording:

If a file has an image extension such as .png or .jpg but its contents are not a valid image, Claude Code falls back to returning text content when the file is readable as text, instead of treating it as image data.

The same clarification should also appear in the Agent SDK Read tool docs so SDK users know they must branch on the returned output type rather than assuming it from the path suffix alone.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageLine(s)Context
https://code.claude.com/docs/en/tools-reference252-255Read tool behavior explains image handling but not the mismatched-extension text fallback
https://code.claude.com/docs/en/agent-sdk/typescript1724, 2136-2152TypeScript SDK docs describe Read as handling text/images and show text vs image output shapes
https://code.claude.com/docs/en/agent-sdk/python2473-2489Python SDK docs split Read output into text vs image cases without noting content-based fallback

Total scope: 3 pages affected

Relevant behavior changed in v2.1.144.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#embedding generation#cache error#pipeline error#runtime error#dependency conflict

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Read tool docs omit text fallback for files with image extensions but non-image contents