[DOCS] Image too large error docs still say pasted images remain in history and require manual removal
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/errors#image-was-too-large
Section/Topic
"Image was too large" under Request errors
Current Documentation
The current error documentation says:
A pasted or attached image exceeds the API's size or dimension limits.
It then shows this remediation:
Image was too large. Double press esc to go back and try again with a smaller image. API Error: 400 ... image dimensions exceed max allowed size
The page also says:
The image stays in conversation history after the error, so every subsequent message fails with the same error until you remove it.
And the suggested fix is entirely manual:
Press Esc twice and step back past the turn where the image was added Resize the image before pasting. The API accepts images up to 8000 pixels on the longest edge for a single image, or 2000 pixels when many images are in context. * Take a tighter screenshot of the relevant region instead of the full screen
What's Wrong or Missing?
This appears outdated for Claude Code v2.1.126. The changelog entry says oversized pasted images are now handled automatically:
Fixed pasting an image larger than 2000px breaking the session -- images are now downscaled on paste, and oversized images in history are automatically removed and the request retried
The current docs still describe the old failure mode: pasted/attached images remain in conversation history, every subsequent message fails, and the user must manually step back and resize/remove the image. That contradicts the new behavior for pasted images larger than 2000px, where Claude Code should downscale on paste and automatically remove oversized images from history before retrying.
The page may still need to cover cases where an image cannot be repaired automatically, but it should distinguish those residual failure cases from the new automatic pasted-image handling.
Suggested Improvement
Update the "Image was too large" section to describe the current behavior introduced in v2.1.126:
- Explain that pasted images larger than 2000px are downscaled on paste.
- Explain that if an oversized image already in history causes a request failure, Claude Code automatically removes it and retries the request.
- Keep manual Esc/resize/tighter-screenshot guidance only for cases that still cannot be handled automatically, such as unsupported attachment paths or images that still exceed API limits after processing.
- Consider changing the blanket sentence "The image stays in conversation history..." to conditional wording so users do not expect every subsequent message to fail after v2.1.126.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/errors#image-was-too-large | 385-400 | Primary "Image was too large" troubleshooting guidance still describes the pre-v2.1.126 manual recovery flow |
Release context: Claude Code v2.1.126 says pasted images larger than 2000px are now downscaled on paste, and oversized images already in history are automatically removed before retrying the request.
Total scope: 1 primary docs page affected.
4 Comments
Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.
Verified against the latest docs; this still appears unresolved.
Issue #55192 Verification
Title: [DOCS] Image too large error docs still say pasted images remain in history and require manual removal
Issue Date: 2026-05-01
Verification Date: 2026-06-27
Status: RESOLVED
---
Issue Summary
The issue reports that the "Image was too large" troubleshooting section on the errors page described the pre-v2.1.126 manual recovery flow as current behavior: that a pasted image remains in conversation history and forces the user to manually step back, resize, or retake the screenshot on every subsequent message. It asked for the docs to explain the automatic downscale-on-paste and automatic-removal-from-history retry flow introduced in v2.1.126.
---
Verification Results
Claim 1: The page says "The image stays in conversation history after the error, so every subsequent message fails with the same error until you remove it."
Status: RESOLVED
Evidence: At https://code.claude.com/docs/en/errors#image-was-too-large, the body paragraph (line 560) has been rewritten to describe the new behavior first and conditionalize the older failure mode to versions before 2.1.142:
The blanket sentence the issue quoted no longer appears. The "stays in conversation" wording is now scoped to versions before 2.1.142, and a
{/* min-version: 2.1.142 */}directive in the source tags the new behavior to that version.Verdict: The unqualified claim about images remaining in history has been replaced with conditional, version-scoped wording.
---
Claim 2: The page describes manual recovery (Esc, resize, tighter screenshot) as the only path forward.
Status: RESOLVED
Evidence: At https://code.claude.com/docs/en/errors#image-was-too-large, the manual Esc-twice-and-step-back recovery (line 560) is now explicitly framed as a fallback for pre-2.1.142 versions rather than a current workflow:
The "What to do" bullets (lines 564-565) are retained as preventive guidance:
These are reasonable proactive steps rather than recovery steps, and they do not contradict the new automatic behavior. The follow-up section "Unable to resize image" at lines 567-583 covers the residual failure mode the issue asked the page to document, explaining that "Claude Code normally resizes large images automatically" and describing what to do when the native image processor cannot process the file.
Verdict: The manual recovery flow is no longer presented as the primary path. The page describes automatic replacement plus retry as the current behavior, scopes the manual Esc flow to pre-2.1.142 versions, and documents the residual failure mode in a dedicated follow-up section.
---
Claim 3: The page should explain that pasted images larger than 2000px are downscaled on paste and that oversized images in history are automatically removed before retrying.
Status: RESOLVED
Evidence: At https://code.claude.com/docs/en/errors#image-was-too-large, line 560 states:
This sentence directly addresses the second half of the claim (oversized images in history are automatically handled and the request retried). The 2000-pixel threshold and the "Claude Code normally resizes large images automatically" framing appear at lines 564 and 578, and the "Unable to resize image" section at lines 567-583 elaborates the automatic-resize behavior.
The wording differs slightly from the suggestion in the issue ("downscaled on paste" vs "replaces the unprocessable image with a text placeholder"), but the substantive content the issue asked for — automatic handling rather than a stuck session, with manual steps reserved for residual cases — is now present.
Verdict: The page documents the new automatic behavior, with the 2000-pixel and 8000-pixel thresholds retained as preventive guidance.
---
Current State
| Claim | Status |
|-------|--------|
| Blanket "image stays in conversation history" sentence | RESOLVED |
| Manual recovery flow presented as primary path | RESOLVED |
| Page documents automatic handling (downscale / replace-and-retry) for current versions | RESOLVED |
---
Suggested Fix
N/A - issue has been resolved. The "Image was too large" section on https://code.claude.com/docs/en/errors now describes the post-v2.1.142 automatic replace-and-retry behavior, scopes the pre-2.1.142 manual recovery to that older version line, and retains the "Unable to resize image" follow-up section for the residual failure case.
---
References
---
Conclusion & Recommendation
Primary Concern: The "Image was too large" docs described the pre-v2.1.126 manual recovery flow as current and did not reflect the new automatic handling.
Resolution Status: RESOLVED
Recommendation: CLOSE
The current page conditionalizes the old failure mode to versions before 2.1.142, documents the automatic replace-and-retry behavior introduced after v2.1.126, and retains the manual preventive guidance only as a separate "Unable to resize image" follow-up section, addressing all three of the issue's substantive concerns.
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.