claude-code - 💡(How to fix) Fix API Error: 400 — surrogates not allowed when dragging macOS screenshots

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?

Bug Report

Claude Code version: 2.1.158 (latest as of 28 May 2026) Platform: macOS Started: ~28 May 2026, after a Claude Code update

Error message

API Error: 400 The request body is not valid JSON: str is not valid UTF-8: surrogates not allowed: line 1 column 1 (char 0)

Steps to reproduce

1. Take a macOS screenshot (Cmd+Shift+4 or Cmd+Shift+3)
2. Drag the screenshot PNG file into the Claude Code terminal window
3. Error fires immediately — the request never reaches the model

Also triggers on

• Fetching a PDF via Claude Code tools

Root cause (suspected)

macOS screenshots carry kernel-protected binary extended attributes (com.apple.macl, com.apple.metadata:kMDItemScreenCaptureGlobalRect, etc.) that are not valid UTF-8. It appears a recent Claude Code update started reading or including xattr data when processing dragged image files. When Claude Code tries to encode that binary data as a UTF-8 JSON string, the API rejects the whole request body with the surrogate error.

Verified: xattr -l screenshot.png returns data that fails data.decode('utf-8').

What I ruled out

• Mac reboot — did not fix
• Clearing conversation / starting fresh — did not fix
• Cache files (~/.claude/image-cache/, ~/.claude/paste-cache/) — all valid UTF-8
• Config/settings/memory files — all valid UTF-8
• The PNG content itself — base64-encodes cleanly

Attempted workaround — did NOT work

Copying to /tmp/ and running xattr -c does not resolve the error. com.apple.macl is a kernel-protected attribute that survives the strip.

What Should Happen?

Claude Code should silently skip or base64-encode binary xattrs rather than including them as UTF-8 strings in the request body.

Error Messages/Logs

Error message (exact):
  API Error: 400 The request body is not valid JSON: str is not valid UTF-8:
  surrogates not allowed: line 1 column 1 (char 0)            

  Session metadata:
  apiErrorStatus: 400
  version:        2.1.158
  entrypoint:     cli
  sessionId:      a1da10df-4d3a-4902-ae4c-79a7d29e766e
  cwd:            /Users/dieter.fotino
  gitBranch:      HEAD
  userType:       external

Steps to Reproduce

Take a screenshot Drag and Drop it into Claude working from Terminal

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

Last known-good session: 26 May 2026, v2.1.150

Claude Code Version

claude-sonnet-4-6 - The regression is purely on the Claude Code CLI side, not the model.

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

First errored session: 27 May 2026, v2.1.150 (same version — no visible version bump) Current version at time of reporting: 2.1.158