Oversized images in resumed conversations should auto-downscale instead of hard-blocking the turn
Summary
When a Claude Code session accumulates an image larger than the API's per-image dimension limit (~2000px on a side) in its conversation history — typically from a screenshot tool, an MCP image server's output, or an inline [photo] attachment — every subsequent turn returns a hard error:
An image in the conversation exceeds the dimension limit for many-image requests (2000px).
Run /compact to remove old images from context, or start a new session.The session is otherwise alive (TUI rendering, plugin polling, network healthy) but cannot make a single API call. The only recovery path is /compact (which uses tokens to summarize the entire history) or /clear (which throws away context). For long-running sessions resumed via --resume, this is a real cliff: a single oversized screenshot from days ago can permanently brick the session until manually compacted.
We're hitting this 4+ times per day across multiple long-running sessions on Claude Code 2.1.122 (macOS + Linux, both via --continue and --resume).
Repro
- Start a Claude Code session in a project that has an MCP server which returns images (e.g., XcodeBuildMCP screenshots, nano-banana, browser tools).
- Take a screenshot or generate an image with any axis ≥ 2001px (a Retina mac screenshot is ~3024×1964, very close to the limit; some Android emulator screenshots exceed it).
- Continue the conversation for a few more turns — image stays in history.
- Eventually, hit a turn where the API consolidates the image batch and rejects it.
- From that point on, every prompt errors with the message above. TUI is alive, plugin still polls, but no model call can succeed.
Expected
Either:
- Auto-downscale at injection time: when an image returned by a tool/MCP exceeds 2000px on either axis, Claude Code resizes it (Lanczos resampling, preserve aspect ratio) before injecting into the message history. Original full-res can stay on disk if the caller needs it.
- Auto-strip on conflict: when an API call fails with the dimension-limit error, Claude Code transparently retries by either dropping or downsizing the offending image, instead of surfacing a hard wall to the user.
- At minimum, a config flag (
maxImageDimensionor similar) so users can opt into auto-downscale globally.
Actual
Hard error, session unusable until /compact runs. For sessions driven by a Telegram bot or other automation, the user has no way to even know the session is stuck — it just stops replying.
Why it matters
- Long-running sessions resumed via
--resumeaccumulate old screenshots over days; the cliff is invisible until it lands. - Telegram-channel-driven workflows (
--channels plugin:telegram@claude-plugins-official) have no way to surface the error to the user — the bot silently stops responding. - Operator workaround (manual
/compact) costs tokens AND interrupts whatever was in flight.
Environment
- Claude Code: 2.1.122 (Linux + macOS, multiple machines)
- Sessions: long-running, resumed daily via
--resume, frequently process screenshots from XcodeBuildMCP / chrome-devtools / nano-banana /tmux capture-panestyle tools.
Workarounds we're using
- Detect the error string in tmux pane output via an external monitor and auto-fire
/compact. - Considered building a downscale wrapper around tool outputs but feels like Claude Code's job, not ours.
Happy to provide more diagnostic data if useful.
6 Comments
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
Facing basically the same error, as reported in https://github.com/anthropics/claude-code/issues/55414 though using Claude Desktop and getting a slightly different error message.
+1, hitting this routinely on a real workflow: visual QA of an Android sample app, where each demo screen is captured via
mcp__computer-use__screenshot(or an emulator screen-record frame extraction) and shown to the model so it can iterate on the rendering. After ~5–8 captures, the session bricks mid-iteration with the dimension error — even when individual captures are well under any "many images" threshold a human would expect.Two extra failure modes worth noting on top of the one in the OP:
mcp__computer-use__screenshoton a 5K Mac display.Auto-downscale to ~1800px on the long side at the harness level (before the bytes hit the API) would single-handedly fix this for both new and resumed sessions. The image is already going to be downsampled by the model internally; lossless 4K screenshots in conversation history aren't useful, they're just a session-killer.
Happy to test a fix on a Claude Max plan if a beta build is available.
Closing for now — inactive for too long. Please open a new issue if this is still relevant.
A data point on why auto-downscale needs care here.
I measured what actually reaches the model. A retina full-page capture at 3066 x 28800 arrived as 276 x 2600. The resize preserves aspect ratio, so on a very tall image the long edge is the height, and pulling the height under the cap drags the width down with it. Roughly 11x on both axes, about 99% of the pixels gone. 14pt body text ends up under 3px tall.
So downscaling to fit makes the request succeed, but the image is unreadable by the time it lands. The turn stops erroring and starts silently guessing instead, which is harder to debug than the hard error is.
If auto-downscale ships, two things worth considering:
Happy to share the measurements if useful.
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.