claude-code - 💡(How to fix) Fix [BUG] API Error: image dimension limit (2000px) crashes session with no recovery path

Preflight Checklist

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

What's Wrong?

When a conversation accumulates multiple images (screenshots, charts, generated PNGs), the API eventually throws:

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

This has killed 3+ productive sessions mid-work for me, each time losing significant conversation context during deep analysis tasks.

The problem isn't the limit itself — it's the complete lack of recovery options:

No identification — The error doesn't say which image triggered it. In a session with 10+ screenshots/charts, there's no way to know which one is the culprit. No way to clear images — There's no command like /clear-images or /drop-image <n> to remove offending images and continue the session. The only option is to abandon the session entirely. No warning before the threshold — The error hits suddenly. There's no progressive warning like "You have 8/10 images in this conversation, consider clearing some" that would let users proactively manage it. No graceful degradation — Instead of dropping the oldest/largest image and continuing, the entire API request fails and the session becomes unusable. Expected behavior (any of these would help):

Tell me WHICH image caused the error (index, source, dimensions) Provide a /clear-images or /drop-image command to remove images without losing conversation context Warn at ~80% of the limit so users can proactively manage Auto-downscale images above the threshold instead of hard-failing Allow continuing the session by automatically dropping the oldest images Environment:

Claude Code CLI (macOS, Darwin 24.6.0) Model: claude-opus-4-6 Typical workflow: code analysis + browser screenshots + generated chart PNGs Impact: High — this interrupts long-running analysis sessions where the conversation context is the most valuable part. Having to restart and re-explain hours of context via exported .docx files is a significant productivity loss.

What Should Happen?

Tell me WHICH image caused the error (index, source, dimensions) Provide a /clear-images or /drop-image command to remove images without losing conversation context Warn at ~80% of the limit so users can proactively manage Auto-downscale images above the threshold instead of hard-failing Allow continuing the session by automatically dropping the oldest images

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 (CLI or desktop app)
2. Work on a task that involves multiple screenshots or generated images (e.g., browser screenshots, chart PNGs, outcome check plots)
3. Continue working until ~10+ images accumulate in the conversation
4. At some point, any tool call triggers the error: "An image in the conversation exceeds the dimension limit for many-image requests (2000px). Start a new session with fewer images."
5. The session is now permanently broken — every subsequent message returns the same error
6. No command exists to clear images or identify which image caused it

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

No response

Claude Code Version

claude-opus-4-6

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

This has crashed 3+ sessions during deep analytical work. The impact is high because these are long-running sessions where the accumulated conversation context IS the primary value — losing it means hours of rework. The error seems to trigger when a combination of many images + at least one large image (e.g., a matplotlib chart saved at default DPI) is present, but there's no way to confirm since the error doesn't identify the image.