[BUG] Image dimension limit (2000px) error blocks many-image requests instead of auto-resizing

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When I work with multiple screenshots in a single session (e.g. UI verification flows where I capture several screenshots from a simulator/emulator and ask Claude to analyze them), the request fails with the following error:

An image in the conversation exceeds the dimension limit for many-image requests (2000px). Start a new session with fewer images.

Problems with the current behavior:

1. The error blocks the entire request instead of automatically downscaling the offending image. Modern phones and simulators (iPhone 15 Pro, Pixel devices, large desktop displays) routinely produce screenshots wider or taller than 2000px, so this hits real users constantly.
2. The recovery suggestion is unhelpful. "Start a new session with fewer images" forces the user to lose all conversation context and re-do their work, even though the actual problem is just one image being slightly over the threshold.
3. There is no client-side resize/compression step before sending. Claude Code already shells out for screenshots (xcrun simctl io ... screenshot, adb exec-out screencap, Playwright snapshots) and could resize them to be safely under the limit before attaching to the request.
4. The error does not say which image is over the limit, making it hard to selectively remove or replace the bad image. With many images attached, the user has to guess.

This is especially painful in UI verification workflows (which the docs themselves recommend) where multiple screenshots per turn are normal.

What Should Happen?

One or more of the following:

1. Automatically downscale any image whose largest dimension exceeds 2000px before attaching it to the request. A simple proportional resize to max 2000px on the longest side would solve this without quality loss for almost all use cases.
2. If downscaling is not possible, the error should:

• Identify which specific image(s) are over the limit (filename, index, or path).
• Allow the user to drop just those images and retry within the same session, instead of forcing a new session.

1. Document the limit clearly in the screenshots/image-handling section of the docs so users can pre-resize on their side if they prefer.

The ideal behavior is option 1 (transparent auto-resize) since the 2000px limit is a transport constraint, not a semantic one — a 4000px screenshot downscaled to 2000px conveys the same information for almost all UI/code-review tasks.

Error Messages/Logs

An image in the conversation exceeds the dimension limit for many-image requests (2000px). Start a new session with fewer images.

Steps to Reproduce

1. Start a Claude Code session.
2. Take several screenshots from a high-resolution source. For example, on iOS Simulator:

``bash
xcrun simctl io booted screenshot screen1.png
xcrun simctl io booted screenshot screen2.png
xcrun simctl io booted screenshot screen3.png
``
(iPhone 15 Pro Simulator screenshots are 1179x2556px — well over the 2000px limit on the long side.)

1. Ask Claude to read all of them in one turn, e.g. Read screen1.png, screen2.png, screen3.png and tell me if the layouts match.
2. The request fails with: An image in the conversation exceeds the dimension limit for many-image requests (2000px). Start a new session with fewer images.
3. The session is effectively poisoned — even unrelated follow-up requests in the same session can keep failing because the offending image is still in conversation history.

Reproducible reliably with any screenshot tool that produces images >2000px on the longest dimension (modern simulators, Retina displays, Playwright fullPage: true snapshots, etc.).

Workaround I currently use: manually resize every screenshot with sips -Z 2000 file.png before reading it, which is tedious and easy to forget.

Claude Model

None

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.119 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

• This affects UI/UX verification workflows that are explicitly recommended in the docs ("take screenshots and review them").
• Frequency: I hit this multiple times per week, every time I do multi-screen verification.
• Suggested fix complexity: low. The CLI already controls how images are encoded and uploaded; adding a sharp/jimp resize step (or even just calling sips on macOS / magick elsewhere) for any image over 2000px on the longest side would resolve this transparently for almost all users.
• Tested on macOS 15 (Darwin 25.4.0), Claude Code 2.1.119, Anthropic API. Same behavior reported by other users in Discord.