KBCodeKB
Unverified

Fix Claude Code API Error 400: Oversized Image Permanently Breaks Conversation — Recovery Workarounds

When a user pastes an image exceeding the 2000px dimension limit into Claude Code (any interface: VS Code extension, Claude Desktop, claude.ai, Chrome extension), the API returns HTTP 400 with 'messages.X.content.Y.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels'. The critical bug: the oversized image REMAINS in conversation history, causing EVERY subsequent request — even plain text messages — to fail with the same 400 error. The conversation is permanently dead. `/compact` sometimes works but not reliably. The issue has 90 reactions and 110 comments confirming widespread impact across all platforms. Multiple community workarounds exist: (1) 'Physician, Heal Thyself' method — ask Claude in a new session to extract and fix the session's JSONL file by removing the oversized base64 image data, (2) Session replay via JSONL reconstruction, (3) Manual JSONL editing to remove the offending image blocks. The root cause is that Claude Code does not validate image dimensions at upload time and does not provide UI to remove failed images from conversation history. Latest Claude Code as of June 2026 is v2.1.177.

Symptoms

  • Pasting an image >2000px into Claude Code returns HTTP 400 error about image dimensions exceeding 2000 pixels
  • After the initial error, ALL subsequent plain text messages also fail with the same 400 error
  • The conversation becomes permanently unusable — no way to recover without starting a new session
  • `/compact` sometimes recovers the session but is not reliable
  • Affects Claude Code VS Code extension, Claude Desktop, claude.ai web, and Chrome extension
  • With 1M context windows, the bug has a larger impact window — sessions can hit the error at only 42% of context usage

Error signatures

API Error: 400
messages.*.content.*.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels
invalid_request_error
At least one of the image dimensions exceed max allowed size

Possible causes

  • Claude Code does not validate image dimensions at paste/upload time. The oversized image is added to conversation history before the API call, and when the API rejects it, the image remains in the local conversation state.
  • The conversation history is stored as a JSONL file in `~/.claude/sessions/`. The oversized base64 image data persists in this file even after the API returns an error. Every subsequent request includes the full conversation history, which includes the offending image.
  • The `/compact` command attempts to summarize and truncate conversation history, but the base64 image data may not be excluded during compaction — it's treated as part of a message's content array and may be preserved across compactions.
  • The Claude Chrome extension can independently add screenshots to the conversation without user action, creating a scenario where the user didn't even intentionally paste an image but their session is still broken.

Solutions

Prevention: Use Image Resizing Before Pasting

risk: lowgithubpublished

The most reliable prevention is to resize images before pasting them into Claude Code. On macOS, use built-in Preview or `sips` to resize images to under 2000px on the longest dimension. On Linux, use ImageMagick (`convert` or `mogrify`). This prevents the error entirely by ensuring images never exceed the API limit.

  1. Before pasting an image into Claude Code, check its dimensions.
  2. On macOS: `sips -g pixelWidth -g pixelHeight <image>` then resize: `sips -Z 1800 <image>` (resizes longest side to 1800px).
  3. On Linux: `identify <image>` then `convert <image> -resize 1800x1800 <image-resized>`.
  4. Paste the resized image instead of the original.
  5. If using the Chrome extension, disable automatic screenshot capture in extension settings to prevent unintended oversized images.

Commands

sips -g pixelWidth -g pixelHeight image.png
sips -Z 1800 image.png
identify image.png
convert image.png -resize 1800x1800 image-resized.png

Risks

  • Resizing may reduce image quality or legibility of text in screenshots.
  • PDF screenshots or full-page captures may still be too large even after resizing.

Verification

  • Step 1: Run `sips -g pixelWidth -g pixelHeight <image> 2>&1` → expect both dimensions ≤ 2000px after resize.
  • Step 2: Paste the resized image into Claude Code → expect NO 400 error about image dimensions.
✓ 0 verified✕ 0 failed

Manual JSONL Editing — Remove Oversized Image Blocks Directly

risk: lowgithubpublished

If the Physician Heal Thyself method doesn't work (e.g., no Claude Code access), manually edit the session JSONL file. Each message is a JSON object on a separate line. Find lines containing large base64 image data (identifiable by `data:image/` and long base64 strings), and either remove those lines entirely or strip the base64 data from the content array while preserving the text portions of the message.

  1. Find your broken session: `ls -lt ~/.claude/sessions/` — the most recent file is likely the broken one.
  2. Back up the file: `cp session-<id>.jsonl session-<id>.jsonl.bak`.
  3. Use a script to remove lines or content blocks: `python3 -c "import json, sys; [print(json.dumps(m)) for m in [json.loads(l) for l in open(sys.argv[1])] if not any('data:image/' in str(c.get('source',{}).get('data','')) and len(str(c.get('source',{}).get('data',''))) > 10000 for c in m.get('content',[]))]" session-<id>.jsonl > session-<id>-fixed.jsonl`.
  4. Replace the original: `mv session-<id>-fixed.jsonl session-<id>.jsonl`.
  5. Resume: `claude --resume <id>`.

Commands

ls -lt ~/.claude/sessions/
cp session-<id>.jsonl session-<id>.jsonl.bak
python3 -c "import json,sys; lines=[json.loads(l) for l in open(sys.argv[1])]; [print(json.dumps(l)) for l in lines if not any('data:image/' in str(c.get('source',{}).get('data','')) and len(str(c.get('source',{}).get('data','')))>10000 for c in l.get('content',[]))]" session-<id>.jsonl > session-<id>-fixed.jsonl
mv session-<id>-fixed.jsonl session-<id>.jsonl
claude --resume <id>

Risks

  • Manual JSONL editing can corrupt the session file if not done carefully. Always back up first.
  • Removing entire message lines may lose text context that was in the same message as the image.
  • The specific content array structure may vary between Claude Code versions — the script may need adjustment.

Verification

  • Step 1: Run `wc -l ~/.claude/sessions/<id>.jsonl 2>&1; echo exit=$?` → note the line count before editing.
  • Step 2: Run the Python cleanup script → expect reduced line count (image-containing messages removed).
  • Step 3: Run `claude --resume <id> 2>&1 | head -5` → expect successful session resume without 400 error.
✓ 0 verified✕ 0 failed

Physician Heal Thyself — Ask Claude to Fix the Session JSONL (Recommended)

risk: lowgithubpublished

Community member @CatalanCabbage discovered the most reliable recovery method: start a NEW Claude Code session, provide the error message, and ask Claude to locate and fix the broken session's JSONL file by removing the oversized base64 image blocks. Claude can read the JSONL, identify message blocks containing base64 image data exceeding the limit, rewrite the file without those blocks, and then you can resume the session with `claude --resume <id>`.

  1. Copy the full error message including the specific message index numbers (e.g., 'messages.21.content.91.image.source.base64.data').
  2. Start a fresh Claude Code session: `claude` (new session).
  3. Tell Claude: 'A previous session is broken because of an oversized image. The error is: <paste error>. Find the session in ~/.claude/sessions/, remove the oversized base64 image blocks from the JSONL file, and tell me the session ID so I can resume it.'
  4. Claude will read the session JSONL, strip the oversized image blocks, rewrite the file, and provide the session ID.
  5. Resume the fixed session: `claude --resume <session-id>`.

Commands

claude
claude --resume <session-id>
ls -lt ~/.claude/sessions/ | head -5
wc -c ~/.claude/sessions/*.jsonl

Risks

  • The new session will consume API tokens for the recovery operation.
  • If the JSONL file is very large, the fix may be slow.
  • The Claude Chrome extension cannot use this method (no filesystem access).

Verification

  • Step 1: Run `ls -lt ~/.claude/sessions/ 2>&1; echo exit=$?` → expect list of session JSONL files. Note the most recently modified file (your broken session).
  • Step 2: In a new `claude` session, ask Claude to read the broken session's JSONL and remove base64 image blocks >100KB → expect Claude to report which blocks were removed and provide a session ID.
  • Step 3: Run `claude --resume <fixed-session-id>` → expect successful resume without the 400 error.
✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "3ecfc780-2689-41e1-9fec-b35f9aed724e",
  "slug": "fix-claude-code-api-error-400-oversized-image-permanently-breaks-conversation-recovery-workarounds-dqc4vn",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-claude-code-api-error-400-oversized-image-permanently-breaks-conversation-recovery-workarounds-dqc4vn"
}
← Back to all issuesPowered by CodeKB