[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.