›_ Claude Code Issues
Claude Code Issues / #16169

[BUG] [CRITICAL] Unsupported image formats permanently break Claude Code sessions - no error recovery

Resolved 💬 3 comments Opened Jan 3, 2026 by hermannakruse Closed Jan 7, 2026

Bug Report: HEIC Image Format Causes Non-Recoverable Session Failure

Bug Report for GitHub Issue

Title

[BUG] [CRITICAL] Unsupported image formats permanently break Claude Code sessions - no error recovery

Description

Summary:
When Claude Code encounters an image format it cannot process, instead of displaying an error message and continuing normally, it permanently corrupts the entire session. All subsequent messages (even simple text) fail with "Could not process image" error, forcing the user to abandon the session completely.

This is a critical error handling failure - unsupported formats should be rejected gracefully, not destroy the session.

Environment:

  • Claude Code Version: 2.0.76
  • Platform: macOS (Darwin 25.2.0)
  • Image Format: HEIC/HEIF with HEVC compression
  • File Type: ISO Media, HEIF Image HEVC Main 10 Profile

Steps to Reproduce

  1. Start a Claude Code session
  2. Attempt to read any HEIC image file:

``bash
claude
> Read /path/to/image.HEIC
``

  1. Observe initial error: "Unable to determine image format"
  2. Try to send any subsequent message (even simple text)
  3. Observe all messages fail with API error: "Could not process image"

Expected Behavior

When encountering an unsupported image format, Claude Code should:

  1. Display a clear error message: "Cannot process image: HEIC format not supported. Supported formats: JPEG, PNG, GIF, WebP"
  2. Continue working normally - accept subsequent user messages
  3. Not corrupt the session - user can continue their work
  4. Optional: Suggest workaround (convert to JPEG/PNG)

The session must remain usable - this is basic error handling.

Actual Behavior

  1. Claude Code attempts to process HEIC file
  2. Local error: "Unable to determine image format"
  3. Instead of stopping and showing error, corrupted image data sent to Claude API
  4. API rejects with: 400 invalid_request_error: "Could not process image"
  5. CATASTROPHIC FAILURE: Session permanently broken
  • Every subsequent message fails with same error
  • Simple text messages fail
  • No commands work
  • No recovery possible
  1. User must abandon all work in that session

This is a catastrophic error handling failure - unsupported images should never break the entire session.

Error Sequence from Debug Logs

2026-01-03T14:32:34.758Z [ERROR] Error: Unable to determine image format
2026-01-03T14:32:38.095Z [ERROR] Error: Unable to determine image format
2026-01-03T14:32:39.331Z [ERROR] Error streaming, falling back to non-streaming mode:
  400 {"type":"error","error":{"type":"invalid_request_error",
  "message":"Could not process image"},"request_id":"req_011CWkcDY1XZiehL3nhmBYxF"}
2026-01-03T14:32:40.037Z [ERROR] Error in non-streaming fallback:
  400 {"type":"error","error":{"type":"invalid_request_error",
  "message":"Could not process image"},"request_id":"req_011CWkcDdfbkhdMPAqpUVwdf"}

Every subsequent message triggers the same error pattern.

Impact

Severity: CRITICAL

Primary Problem: Catastrophic error handling failure

  • ANY unsupported image format destroys entire session
  • No graceful degradation - complete failure instead of error message
  • No recovery mechanism - session permanently unusable
  • Data loss - all work in session must be abandoned

Secondary Problem: HEIC is common trigger

  • Affects all macOS/iOS users (HEIC is default camera format since iOS 11)
  • Silent failure - users don't know HEIC is unsupported until session breaks
  • Likely affects other unsupported formats too (SVG, TIFF, BMP, etc.)

User Experience:

  1. User asks Claude to analyze a photo
  2. Claude attempts, fails silently
  3. Entire session destroyed
  4. User loses all conversation context and work
  5. Must start completely over

This violates basic error handling principles - errors should be contained, not cascade into total failure.

Workaround

Convert HEIC to JPEG before reading:

# Using macOS built-in sips tool
sips -s format jpeg input.HEIC --out output.jpg

# For optimal size (under 256KB limit)
sips -Z 800 input.HEIC --out output.jpg

Proposed Solutions

REQUIRED (Critical Error Handling):

Option 1: Pre-flight Format Validation (Prevents the problem)

  • Validate image format BEFORE sending to API
  • Check file extension AND magic bytes
  • Reject unsupported formats immediately with clear message
  • Session continues normally - no corruption

Option 2: API Error Recovery (Contains the damage)

  • When API returns "Could not process image":
  • Remove corrupted image from conversation context
  • Display error to user: "Cannot process image. Supported formats: JPEG, PNG, GIF, WebP"
  • Allow session to continue - do not propagate error to subsequent messages
  • Add retry logic that excludes the problematic image

Option 3: Conversation Context Cleanup

  • Detect when conversation context contains unprocessable content
  • Implement rollback mechanism to remove problematic messages
  • Preserve rest of conversation history

OPTIONAL (Nice to Have):

Option 4: Add HEIC Support

  • Convert HEIC to JPEG before sending to API
  • Automatic format conversion for common formats

The critical fix is error containment - unsupported formats must not destroy sessions.

Related Issues

  • #1747 - "Could not process image" is non-recoverable (duplicate, closed)
  • #930 - Invalid image format corrupts session (fixed for JPEG/PNG in v1.0.3)
  • #15807 - MCP fails with unsupported image formats
  • #11560 - Read tool crashes on certain PNGs

Note: None of these issues specifically address HEIC format.

Test Files

Sample HEIC file characteristics:

  • Type: ISO Media, HEIF Image HEVC Main 10 Profile
  • Size: 482KB (original), 46KB (resized to 800px)
  • Source: iPhone/iPad camera or screenshots

Additional Context

Supported Formats (per Claude API):

  • image/jpeg ✓
  • image/png ✓
  • image/gif ✓
  • image/webp ✓

Unsupported:

  • image/heic ✗
  • image/heif ✗
  • image/svg+xml ✗

Debug Logs:
Available from affected sessions:

  • ~/.claude/debug/2270b4ae-5f74-4e98-9201-ca1e11fe9cf1.txt
  • ~/.claude/debug/ab026a18-5b47-4b1c-b05b-eec10488a36e.txt

Recommendation

This bug should be prioritized because:

  1. Common occurrence - HEIC is default iOS camera format
  2. No warning - users unaware until session breaks
  3. No recovery - permanent session loss
  4. Easy fix - format validation before processing

---

Reporter: Claude Code User (macOS)
Investigation Date: 2026-01-03
Documentation: Full investigation report available

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗