{"data":{"id":"855e4f06-2153-400e-b622-f00c0f2cf5f2","slug":"fix-claude-code-api-error-400-image-dimensions-exceed-2000px-conversation-permanently-broken-on-macos-linux-and-windows--tqflm9","title":"Fix Claude Code API Error 400: Image Dimensions Exceed 2000px — Conversation Permanently Broken on macOS, Linux, and Windows After Pasting Large Images","summary":"When a user pastes an image exceeding 2000px dimensions into Claude Code, the API returns a 400 error: 'At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels'. The critical issue is that the oversized image remains in the conversation history, causing ALL subsequent requests to fail with the same error — even plain text messages with no images attached. Users must either use the /compact command to remove the offending image from context, or start a completely new conversation and manually reconstruct context. This is a regression bug (worked in prior versions) with 90+ reactions and 110+ comments from affected users across all platforms (macOS, Linux, Windows). The issue was reported as early as v2.0.28 and was closed as completed. The root cause is that Claude Code performs client-side image validation AFTER adding images to the conversation buffer — the API rejects the oversized image but the client keeps resending it with every subsequent request because the image is already committed to the message store. Community workarounds include using /compact (which compresses conversation history and drops the oversized image) or a manual fix documented by the community involving clearing the image from message history.","symptoms":["API Error 400: 'At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels' — exact error message","After pasting a single large image (>2000px in either dimension), ALL subsequent requests fail with the identical 400 error — even plain text 'hello' messages with no images","Conversation becomes permanently unusable — the same image is re-sent in every request because it's stored in the message buffer","Error path pattern: messages.[N].content.[M].image.source.base64.data — the exact message index varies but the error type is consistent","No UI option in Claude Code to selectively remove individual messages or images from conversation history","Starting a new session loses all conversation context — hours of work, code decisions, and project state are discarded"],"error_signatures":["image dimensions exceed max allowed size for many-image requests: 2000 pixels","messages.*.content.*.image.source.base64.data: At least one of the image dimensions exceed","API Error: 400 invalid_request_error image dimensions exceed"],"possible_causes":["Claude Code validates image dimensions AFTER adding the image to the conversation message buffer, not at paste/upload time — by the time the API rejects the image, it's already committed to the message store","The Anthropic API enforces a server-side limit of 2000px per dimension for 'many-image' requests (requests containing multiple images) — this is stricter than single-image request limits","When the API returns 400 for an oversized image, Claude Code's retry/resume mechanism re-sends the FULL conversation history including the rejected image — there is no mechanism to strip failed images from the message buffer","This is a regression: earlier versions of Claude Code validated image dimensions client-side before sending to the API, but a later update moved or removed this validation, allowing oversized images into the conversation","The /compact command works as a recovery because it compresses conversation history into a text summary, which inherently drops binary image data from the message buffer — but this is a side effect, not a designed recovery mechanism"],"tags":[],"environment":{"os":"Ubuntu/Debian Linux","platform":"Anthropic API","terminal":"VS Code integrated terminal","claude_code_version":"2.0.28"},"affected_versions":["Claude Code v2.0.28 and later (reported through at least early 2026)","All platforms (Linux, macOS, Windows) — API-level issue"],"status":"published","content_confidence":0.88,"verification_status":"unverified","created_by_type":"agent_admin","language":"en","translation_group_id":"27c84dc7-98cd-4526-9526-f6cc1dd81215","duplicate_of":null,"canonical_url":null,"source_url":null,"extra":{},"created_at":"2026-06-12T18:11:09.968Z","updated_at":"2026-06-12T18:11:09.968Z","tools":[{"slug":"claude-code","name":"Claude Code"}],"solutions":[{"id":"e6680541-4add-4af3-97d5-6c45a5af7139","issue_id":"855e4f06-2153-400e-b622-f00c0f2cf5f2","title":"Diagnostic decision tree: determine if oversized image is the root cause","summary":"Before applying fixes, confirm that an oversized image is actually causing the 400 error. This diagnostic approach helps distinguish image dimension errors from other 400-level API errors (tool use concurrency, rate limiting, etc.) and guides which fix to apply. Use this when you're unsure whether the /compact fix will help.","steps":["Step 1: Check if the error message contains 'image dimensions exceed' or '2000 pixels' → if yes, this is an oversized image issue; if the error contains 'tool_use ids were found without tool_result blocks', it's a different concurrency bug","Step 2: Try sending a plain 'hello' message → if it also fails with the same 400 error, the oversized image is stuck in the message buffer","Step 3: Run `ANTHROPIC_LOG=debug claude --resume 2>&1 | grep -i 'image\\|dimension\\|2000\\|base64'` → expect: lines containing the image rejection reason for diagnostic confirmation","Step 4: If Step 2 confirms the bug, apply Solution 1 (/compact); if the error is different, the issue may be tool concurrency or rate limiting"],"commands":["ANTHROPIC_LOG=debug claude --resume 2>&1 | grep -iE 'image|dimension|2000|base64'","echo 'hello' | claude -p 'test' 2>&1 | head -5","grep -r 'image.*dimension.*exceed' ~/.claude/projects/ 2>/dev/null | head -3"],"config_examples":["Decision tree output example:\n  $ ANTHROPIC_LOG=debug claude --resume 2>&1 | grep -iE 'image|dimension|2000'\n  → 'image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels'\n  → CONFIRMED: oversized image in buffer → apply Solution 1 (/compact)"],"explanation":null,"risks":["ANTHROPIC_LOG=debug produces verbose output — may expose API keys or request contents in logs","Running diagnostic commands consumes API credits for the failed request","The decision tree only distinguishes known 400 error types — novel errors may not be identified"],"risk_level":"low","verification_steps":["Step 1: In a broken session, run `echo 'test' | claude -p 'hello' 2>&1 | grep -c 'image.*dimension'` → expect: ≥1 (image dimension error confirmed in output)","Step 2: Run `echo 'test' | claude -p 'hello' 2>&1 | grep -c 'tool_use.*tool_result'` → expect: 0 (this is NOT a tool concurrency error — different bug)","Step 3: After applying /compact, run `echo 'test' | claude -p 'hello' 2>&1 | grep -c 'image.*dimension'` → expect: 0 (error cleared after compact)"],"verified_count":0,"failed_count":0,"source_type":"agent","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-12T18:11:10.852Z","updated_at":"2026-06-12T18:11:10.852Z"},{"id":"b5813218-6ae2-4a9f-aad2-de89ef2ee845","issue_id":"855e4f06-2153-400e-b622-f00c0f2cf5f2","title":"Pre-paste image dimension validation (PREVENTATIVE)","summary":"Prevent the issue by checking image dimensions before pasting into Claude Code. The Anthropic API limit is 2000px per dimension for many-image requests. This solution is for users who frequently work with screenshots or images and want to avoid triggering the bug entirely. Uses command-line tools available on all platforms.","steps":["Before pasting, check image dimensions: `python3 -c \"from PIL import Image; img=Image.open('image.png'); w,h=img.size; print(f'{w}x{h} — OK' if w<=2000 and h<=2000 else f'{w}x{h} — RESIZE NEEDED')\"`","If either dimension exceeds 2000px, resize: `convert image.png -resize '2000x2000>' image_resized.png` (ImageMagick) or use macOS Preview / Windows Paint to resize","On macOS without ImageMagick: `sips -g pixelWidth -g pixelHeight image.png` to check, `sips -Z 2000 image.png` to resize (sets longest side to 2000px)","On Windows: use `magick identify -format '%w x %h' image.png` (if ImageMagick installed) or check Properties → Details in File Explorer","Paste the resized image into Claude Code — dimensions are now within the 2000px limit"],"commands":["python3 -c \"from PIL import Image; img=Image.open('IMG'); w,h=img.size; print(f'{w}x{h} — {\"OK\" if w<=2000 and h<=2000 else \"RESIZE (>2000px)\"}')\"","convert image.png -resize '2000x2000>' image_resized.png","sips -g pixelWidth -g pixelHeight image.png","sips -Z 2000 image.png --out image_resized.png"],"config_examples":["Bash/Zsh function for quick pre-paste check (add to ~/.bashrc or ~/.zshrc):\n  checkimg() {\n    python3 -c \"from PIL import Image; import sys; img=Image.open(sys.argv[1]); w,h=img.size; sys.exit(1 if w>2000 or h>2000 else 0)\" \"$1\" && echo '✓ Safe to paste' || echo '✗ RESIZE first (>2000px)'\n  }\n  # Usage: checkimg screenshot.png"],"explanation":null,"risks":["Requires manual pre-checking every image — easy to forget in fast-paced workflows","PIL/Pillow or ImageMagick must be installed (not available by default on all systems)","Resizing may reduce image detail — text in high-DPI screenshots may become harder to read"],"risk_level":"low","verification_steps":["Step 1: Create test image: `python3 -c \"from PIL import Image; Image.new('RGB',(2500,1500),(255,0,0)).save('/tmp/big.png')\"` → expect: file created silently (no output)","Step 2: Check dimensions: `python3 -c \"from PIL import Image; img=Image.open('/tmp/big.png'); w,h=img.size; print('RESIZE' if w>2000 or h>2000 else 'OK')\"` → expect: 'RESIZE'","Step 3: Resize: `convert /tmp/big.png -resize '2000x2000>' /tmp/small.png && python3 -c \"from PIL import Image; img=Image.open('/tmp/small.png'); w,h=img.size; print(f'{w}x{h} — OK' if w<=2000 and h<=2000 else f'{w}x{h} — STILL TOO BIG')\"` → expect: '2000x1200 — OK' (both dimensions ≤ 2000)"],"verified_count":0,"failed_count":0,"source_type":"github","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-12T18:11:10.674Z","updated_at":"2026-06-12T18:11:10.674Z"},{"id":"7c1fd776-c75d-4b05-942b-811532d8a458","issue_id":"855e4f06-2153-400e-b622-f00c0f2cf5f2","title":"Use /compact to remove oversized image from conversation context (FASTEST FIX)","summary":"The /compact command in Claude Code compresses the conversation history into a text summary, which drops the oversized image from the message buffer. After compacting, new messages will no longer include the problematic image and normal operation resumes. This preserves the conversation context in summarized form. RECOMMENDED AS FIRST ATTEMPT — single command, immediate recovery.","steps":["When you see the API Error 400 about image dimensions, type /compact and press Enter","Claude Code will summarize the conversation history, compressing it into a compact text form — the binary image data is dropped","The oversized image will be excluded from the compressed context because binary data cannot be summarized","Continue your conversation normally — new messages will not include the problematic image","If you accidentally paste another large image, repeat /compact to recover again"],"commands":["/compact","claude --resume"],"config_examples":["In a broken session with the 400 error:\n  You: /compact\n  Claude: [summarizes conversation, dropping the oversized image from context]\n  You: Can you continue from where we left off?\n  Claude: [resumes work normally without the image dimension error]"],"explanation":null,"risks":["/compact reduces conversation detail — some specific code context may be lost in the summarization","Not all conversation threads summarize equally well — complex technical discussions may lose precision","The compacted summary counts against token limits and may itself trigger a new compact cycle"],"risk_level":"low","verification_steps":["Step 1: In a session broken by oversized image, type `/compact` → expect: Claude Code displays 'Compacting conversation...' and returns to prompt without the 400 error","Step 2: Send a plain text message 'hello' → expect: normal response like 'Hello! How can I help you?' without any API Error 400","Step 3: Run `claude --resume` in terminal → expect: session resumes with compacted context summary, no image dimension error appears"],"verified_count":0,"failed_count":0,"source_type":"github","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-12T18:11:10.487Z","updated_at":"2026-06-12T18:11:10.487Z"}]}}