Claude Code cache_control 400エラー｜画像貼付の対処法

ムラサキ — Sat, 02 May 2026 08:26:19 +0000

SE歴20年で副業ブログを運営する筆者が、Claude Code Maxプランで自動化パイプラインを動かしているとき、画像をスクショで貼り付けただけで、その後セッション全体が「400エラー」で動かなくなる現象に1週間悩まされました。原因はAnthropic APIの仕様とClaude Code 2.1系の既知バグの組み合わせ。2026年5月時点で確認できた範囲で、エラーの正体・復旧手順・リモートから対応できるかの実際の解決方法を整理します。

ムラサキ

画像だけ貼って送ったあと、何を打っても400が消えない。その絶望感を共有したい。同じパターンで詰まってる人は多いはずです。

TL;DR / 三行要約 10 MIN READ · UPDATED 2026.05

cache_control cannot be set for empty text blocks は画像のみ送信ターンで空テキストブロックが生まれ、セッション全体が400で詰まるバグ（Issue #50375他4件）。
復旧はPCで Esc×2（/rewind）のみ。外出先リモコンからは/rewindが使えず復旧不可。
再発防止は「画像送信時に1文字以上のテキストを必ず添える」だけ。根本修正は2026年5月時点で未提供。

RESULT — Esc×2で即復旧 TOOL — Claude Code 2.1系 + /rewind COST — GitHub Issue 4件・根本修正未提供

「cache_control cannot be set for empty text blocks」とは何のエラーか
「画像のみ貼り付け」でセッションが詰んだ話
エラーの正体–cache_control × 空テキストブロックの組み合わせ
PC側で「詰んだ」セッションを復旧する手順
外出先（リモコン）から復旧できるか–調査と現実解
再発させない予防策
よくある質問
まとめ

「cache_control cannot be set for empty text blocks」とは何のエラーか

ターミナルでこのエラーが突然表示されたら、このページが役に立つはずです。先に結論をいきます。

cache_control cannot be set for empty text blocks は、Anthropic APIが「空のテキストブロックにキャッシュ制御を付けようとした」リクエストを拒否するエラー。Claude Codeで画像のみを貼り付けて送信したターンが原因で、セッションの履歴に空テキストブロックが残り、以降のリクエストがすべて弾かれます。

復旧はPCで Esc を2回押す（/rewind）だけ。詰みの仕組みと再発防止まで説明します。

「画像のみ貼り付け」でセッションが詰んだ話

ブログ自動化パイプライン構築中に遭遇したエラーの記録です。

発生したエラー本文

スクリーンショットだけをペーストしてClaude Codeに送信したターンでは応答が返ってきました。その次のターン以降、何を送っても以下のエラーで止まります。

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.105.content.2.text: cache_control cannot be set for empty text blocks"}}

※ Windows 11、Claude Code Maxプラン、2026年4〜5月の環境で実際に発生したエラーログです。messages.X.content.Y の数字は環境ごとに異なります。

なぜ詰むのか

このエラーが厄介な点は、一度発生するとそのセッション内では何を打っても解消しないこと。画像、テキスト、混在メッセージ、どれを送っても毎回同じ400が返ります。Claude Codeは過去ターンの履歴を毎回サーバーに再送する仕組みなため、壊れた履歴が残っている限り後続のリクエストが弾かれ続ける構造になっているのです。

試した手段（いずれも無効）

以下を試しましたが、どれも効きませんでした。

翌日再開：履歴が残っているため同じエラー
exit → claude -c で前回セッションを再開：履歴ごと再ロードするのでエラーも復活
claude で新規セッション起動：新しいセッションは動くが、壊れたセッションは復帰不可

別セッションで「逃げる」ことはできても、本来作業していたセッションを救う手段はありません。

エラーの正体–cache_control × 空テキストブロックの組み合わせ

cache_control cannot be set for empty text blocks がClaude Codeのセッションを止める理由は、Anthropic公式ドキュメントとGitHub Issueを見れば明らかです。

仕様：空テキストブロックはキャッシュできない

Anthropic APIのプロンプトキャッシング仕様では、cache_control を付けたコンテンツブロックがキャッシュ対象になります。Anthropicの公式ドキュメントでは、空のテキストブロックはキャッシュできないと明記されています。

バグ：画像のみのターンで空テキストブロックが生成される

Claude Code 2.1系で、画像をペーストして添付テキストなしで送信すると、APIへ送られるメッセージのcontent配列に {"type":"text","text":""} という空テキストブロックが残ります。GitHubのIssue #50375に再現手順と問題のあるJSONL構造が報告されています。

厄介なのは、最初のターンは通ってしまうことです。次ターン以降、Claude Codeが履歴を再送する際に空テキストブロックに cache_control が付くか、APIのルール（text content blocks must be non-empty）に引っかかって400エラーで弾かれます。

graph TD
  A["画像のみ貼り付けて送信"] --> B["空テキストブロックが履歴に紛れ込む"]
  B --> C["1ターン目は通ってしまう"]
  C --> D["次ターン以降履歴再送で400エラー"]
  D --> E["セッション全体が動かなくなる"]

PC側で「詰んだ」セッションを復旧する手順

筆者が実際に試してたどり着いた、効く順に並べた復旧フローです。

第一手：/rewind（または Esc 2回）でエラー前まで巻き戻す

筆者の環境で最も確実に効いたのがこれです。/rewind コマンドを実行するか、ターミナルで Esc キーを2回押すと、セッション内のチェックポイント一覧が表示され、エラーが発生する前のターンを選んで巻き戻せます。「Conversation only（会話のみ）」を選べばコードは触らずに会話履歴だけ戻せるので、詰みポイントを切り捨てて作業を続行できます。

/rewindでの復旧手順

STEP1
Escを2回押す

ターミナルでアクティブな状態でEscキーを2回素早く押すと、巻き戻し用のチェックポイント選択画面が立ち上がります。
STEP2
エラー直前のターンを選ぶ

画像を貼り付けたターンの「直前」のチェックポイントを選択します。画像送信ターンを含めて巻き戻すと、空テキストブロックが履歴から消えます。
STEP3
Conversation onlyを選択

コード変更を維持したまま会話だけ戻したい場合は「Rewind conversation only」を選択します。履歴がクリーンな状態に戻り、APIリクエストが通るようになります。

第二手：JSONLトランスクリプトを直接編集する

/rewind が効かないケース（巻き戻し先のターンも壊れている等）では、ローカル保存されているセッションファイルを直接編集します。Claude Codeのセッションは ~/.claude/projects/ 配下のJSONLファイルに記録されており、Issue #24662では壊れたassistantメッセージを切り詰めて claude --continue で再開する手順が有効な回避策として共有されています。

JSONL編集はファイル破壊リスクがあるため、必ず元ファイルをコピーしてから作業してください。Windowsの場合 %USERPROFILE%.claudeprojects 配下にあります。非公式ですが、空テキストブロックを自動除去する fix-jsonl といったコミュニティツールも公開されています。

第三手：新セッションで再開する

現状を保存してとにかく前に進めたいなら、claude で新規セッションを起動して、必要なコンテキストを貼り直すのが最速です。CLAUDE.mdとBUGS.mdを運用していれば、文脈の再現コストはかなり下げられます。CLAUDE.mdの実運用例はClaude Codeで個人サービスを作った正直な話にまとめています。

外出先（リモコン）から復旧できるか–調査と現実解

Claude Codeのリモートコントロール機能を使えば外出先のスマホからもセッションを操作できます。ただし詰みエラーの復旧という観点では、大きな制限があります。

結論：/rewind はリモコンから使えない

Anthropic公式のリモートコントロールドキュメントに記載されたリモコン対応スラッシュコマンドは、/compact、/clear、/context、/usage、/exit、/extra-usage、/recap、/reload-plugins の8つだけです。/rewind を含む「インタラクティブピッカーを表示する系」は、ターミナルUIが必要なためリモコン非対応です。

筆者の検証：iOSとWeb版両方で反応なし

iOSのClaudeアプリとWeb版claude.ai/codeの両方で /rewind をテキスト入力に打ち込みましたが、どちらも反応しませんでした。GitHubのIssue #29156でも報告されている通り、リモコン経由のスラッシュコマンドはプレーンテキストとしてモデルに送られるだけで、CLI側で意図したコマンド処理に変換されません。Esc相当のキー送信もリモコンUIには存在しません。

「外出先で詰んだら何ができるか」の現実解

根本的な復旧はPCに戻るまでできません。これが2026年5月時点の答えです。現実的に取れる選択肢は3つです。

状況	取れる手段	限界
別セッションで作業を続けたい	リモコンから新規セッションを開始	詰んだセッションは死んだまま
帰宅まで放置してOK	そのまま帰宅後に`/rewind`で復旧	数時間ロス
自宅PCにSSH/Tailscaleでアクセス可能	スマホのSSHクライアントで直接ターミナル操作	事前のSSH設定が必要

3つ目のSSH経由アクセスは、Tailscale等で自宅PCに入って直接ターミナルを叩く方式です。リモコンの「公式インタフェース」を通さずTTYに直接届くので、Esc 2回で巻き戻し画面が出ます。設定の手間はありますが、外出先での作業比重が大きい人には最も確実な解になります。

ムラサキ

外出先で詰む可能性があるなら、画像送信時に1文字でいいから添えて送る。この予防運用が一番効きます。

再発させない予防策

復旧より、空テキストブロックを発生させない方が低コストです。

画像を送るときは必ず1文字でも添える

GitHubの複数Issueで報告されている回避策がこれです。画像をペーストするとき、空白でないテキストを1文字でも添えると、空テキストブロックが紛れ込みません。「これ」「確認」「fix」など最低限の単語で十分です。

バックグラウンドタスクと同時送信を避ける

Issue #22923で報告されている別パターンは、バックグラウンドコマンド（/run-in-backgroundなど）の完了タイミングでメッセージを送信すると、空ブロックが混入するというものです。長時間処理を投げているときは、完了を待ってから次のメッセージを送ると安全です。

Claude Codeを最新版に保つ

公式チェンジログでは2.1系の各リリースで関連するエラーハンドリング改善が積み重ねられています。筆者環境では claude doctor での点検と週1回のバージョンアップ確認をルーチンにしています。Claude Code全体の運用設計はClaudeプロンプト888行の運用限界で詳しく整理しています。

よくある質問

Q messages.X.content.Y.text のXとYの数字は何を意味しますか？: A

APIに送られたメッセージ配列のインデックスです。Xはメッセージ番号（会話の何ターン目か）、Yはそのメッセージ内のコンテンツブロック番号。数字は環境やセッションの長さで変わるため、気にする必要はありません。重要なのは「空テキストブロック」が履歴のどこかに存在する事実です。

Q エラーが出ているのに、最初の画像送信ターンは通ったのはなぜですか？: A

画像を含むメッセージはAPIへの送信時に受理されることがあります。問題は次ターン以降です。Claude Codeが過去履歴を再送する際に空テキストブロックがcache_controlの条件に引っかかったり、text content blocks must be non-emptyルールに違反して400が返されます。

Q /rewindで巻き戻したのにエラーが直りません: A

巻き戻し先のチェックポイントに空テキストブロックを含むターンが残っている可能性があります。さらに1〜2ターン手前まで戻すか、JSONLファイルの直接編集または新セッション起動に切り替えてください。

Q Claude Code以外（API直接利用やSDK）でも同じエラーは出ますか？: A

出る可能性があります。Anthropic API側の「空テキストブロックはキャッシュできない」「テキストブロックは非空必須」のルール自体は共通です。SDK利用時は、リクエスト送信前に空のtextコンテンツを除去するバリデーションを自前で組み込むのが確実です。

Q バージョンアップで直る見込みはありますか？: A

2026年5月時点で根本修正の公式アナウンスはありませんが、Claude Codeの公式チェンジログには関連の修正が継続的に入っています。日次〜週次でバージョンを確認し、claude doctorで環境チェックする運用が現状の対応策です。

まとめ

Claude Codeの cache_control cannot be set for empty text blocks 400エラーは、画像のみ貼り付けたターンに空テキストブロックが履歴に残ることが原因です。セッションが詰まったら、3つの対応がある。

まずPC上で /rewind または Esc 2回で巻き戻す。効かなければJSONL直接編集か新セッション起動に移る。リモコン（iOS/Web）からは /rewind が動作しないため、外出先で詰んだらPCに戻るしかない。ただしSSH経由でTTYに直接接続できる環境があれば外出先からも復旧できる。最後に、予防が最も低コスト。画像送信時に1文字でも添えるだけで発生確率が大きく下がる。

Claude Codeを仕事で運用する場合の課題と工夫はClaude Codeで個人サービスを作った正直な話に体系的にまとめているので、合わせて読むと参考になる。

トラブルシューティング | 週末起業ラボ