Read tool: 400 'Could not process image' when reading image files

Bug Description

When Claude Code's built-in Read tool reads an image file (e.g., .jpg, .png, .heic), it includes the image as a content block in the conversation context sent to the Anthropic Messages API. If the image is too large, corrupted, or in an unsupported format, the API returns:

API Error: 400
{"type":"error","error":{"type":"invalid_request_error","message":"Could not process image"},"request_id":"req_011CZpdwiS3zoeXcj9idFKgv"}

This is a hard failure — the entire conversation turn is rejected, not just the image.

Steps to Reproduce

1. Have a large image file on disk (e.g., a photo from a phone camera, typically 3-10 MB HEIC/JPEG)
2. Ask Claude Code to read or process the image file
3. Claude Code's Read tool reads the file and includes it as an image content block
4. The Anthropic API rejects the request with 400 "Could not process image"

This is reproducible when working with MCP workflows that involve file transfers (e.g., backing up phone photos through an MCP server, then trying to verify/read them).

Expected Behavior

Claude Code should:

1. Validate images before sending — check file size and format against API limits before including in the conversation
2. Graceful degradation — if the image can't be processed, return file metadata (path, size, dimensions, MIME type) instead of failing the entire turn
3. Clear error message — tell the user why the image failed (too large, unsupported format, corrupted) and suggest alternatives (e.g., resize, convert format, use bash commands)

Suggested Implementation

When the Read tool encounters an image file:

if image_size > API_MAX_IMAGE_SIZE || !is_supported_format(ext):
    return metadata_only(path, size, mime_type, dimensions)
    + note: "Image too large/unsupported for inline viewing. Use bash commands to process."
else:
    return image_content_block  # current behavior

This prevents the hard 400 failure while still supporting images that are within API limits.

Workaround

In our MCP server, we added binary file detection to our read_file tool so it returns metadata instead of content for image files. But this only prevents the issue when images are accessed through our MCP tool — the built-in Read tool still triggers the error.

Environment

• Claude Code CLI on Linux (Ubuntu, kernel 6.17.0)
• Model: claude-opus-4-6
• Image files: JPEG/PNG from Android phone camera (3-10 MB typical)