「Unable to resize image」が出る原因と対処法 — Claude Code

「Unable to resize image」は、画像が大きすぎるというより、Claude Codeが画像を読み取れない、または縮小できないときのエラーです。Claude Codeは通常、大きな画像を自動で縮小してからAPIに送ります。その縮小の前段で、デコード(画像データの読み解き)か縮小のどちらかが失敗すると止まります。似た文言の「Image was too large」は、寸法が上限を超えたという別のエラーです。

画面に出る文言は、現在のエラー一覧では7種類あります。文言に原因が書かれているものが多いので、まずどれに当たったかを見れば、直し方はほぼ決まります。

7つの文言は3系統に分かれる

エラー一覧に載っている文言を、要旨だけ抜き出すと次のとおりです。省略記号の部分には、実際のピクセル数やデータ量が入ります。

Unable to resize image — image processing is unavailable and dimensions could not be read from the file header. Please convert the image to PNG, JPEG, GIF, or WebP.
Unable to resize image — dimensions exceed the 2000x2000px limit and image processing failed. ...
Unable to resize image (… raw, … base64). The image exceeds the … API limit and compression failed. ...
Unable to resize image — could not verify image dimensions are within the 2000x2000px API limit.
Unable to resize image — it is a CMYK JPEG, which Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. ...
Unable to resize image — it is an animated WebP whose first frame Claude Code cannot decode, and at …px it is over the 2000x2000px limit, so it cannot be sent. ...
Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. ...

これを原因の違いで束ねると、次の3系統になります。

3つ目と7つ目の文言には、元のデータ量(raw)とbase64化後のデータ量(base64)が並んで出ます。縮小や再圧縮の目標は、メッセージに示された上限です。3系統を分けるのは、直し方が違うからです。1つ目は形式を替えれば通ります。2〜4つ目は大きさを替える作業で、5〜7つ目はファイルの中身を作り直す作業になります。

手元の画像の形式・色空間・寸法を確かめる

文言に当たったら、画像そのものを調べます。macOSには sips が標準で入っていて、形式と色空間と寸法をまとめて読めます。次の出力は、v2.1.287のClaude Codeを入れた環境のmacOS(sips-316)で、macOS付属のHEIC画像と、そこから作ったファイルを調べた結果です。

sips -g format -g space -g pixelWidth -g pixelHeight sample.heic

  format: heic
  space: RGB
  pixelWidth: 3840
  pixelHeight: 2160

HEICは、エラー一覧が挙げる対応形式(PNG・JPEG・GIF・WebP)に入っていません。同じ画像をPNGに変換する sips -s format png、JPEGのCMYK版を作って調べた結果は、次のとおりです。

sips -s format png sample.heic --out sample.png
sips -g format -g space -g pixelWidth rgb.jpg cmyk.jpg

rgb.jpg
  format: jpeg
  space: RGB
  pixelWidth: 1000
cmyk.jpg
  format: jpeg
  space: CMYK
  pixelWidth: 1000

format が対応形式か、space がRGBか、pixelWidth と pixelHeight が2000を超えていないか、の3点を見ます。拡張子が .jpg でも、space: CMYK で、しかも寸法が2000pxを超えていれば、5つ目の文言に当たる条件がそろいます。v2.1.269以降はCMYKのJPEGも変換・縮小されます。拡張子では見分けがつかないので、この確認が早道になります。

文言ごとの直し方

直し方は、文言が名指しした原因に合わせます。

macOSで長辺を2000pxに縮めるには、sips -Z 2000 を使います。3840×2160pxのPNGに実行すると、2000×1125pxになりました。

sips -Z 2000 sample.png --out sample-2000.png

注意点は、小さい画像にも同じコマンドを当てると、2000pxまで拡大される点です。拡大を避ける条件付きの書き方は、姉妹記事の「Image was too large」の原因と対処に、実測つきで載せています。

CMYKのJPEGは、色プロファイルを替えてRGBにします。手元で作ったCMYKのJPEGに、macOS標準のGeneric RGB Profileを当てると、space はRGBに戻りました。

sips -m "/System/Library/ColorSync/Profiles/Generic RGB Profile.icc" cmyk.jpg --out fixed.jpg

sipsが使えないWindowsやLinuxでは、ImageMagickで形式変換ができます。WSLでは、v2.1.157で alt+v による画像の貼り付けとWindows 11のスクリーンショット貼り付けが直り、エクスプローラーからのドラッグにも対応しました。貼り付け自体ができないときは、まず版を確かめます。

magick input.heic output.png

拡張子と中身が食い違うファイルの扱い

画像の形式は、拡張子ではなくファイルの中身(先頭のバイト列)で判定されます。v2.0.65で、Readツールが拡張子ではなくバイトから形式を見分けるようになりました。v2.1.144では、拡張子が画像なのに中身が違うファイル、たとえばHTMLを .png で保存したものを読んだときに、会話が回復できなくなる不具合が直っています。現在はテキストとして読み直す動きです。

同じv2.1.144では、MCPサーバーが返したSVGなど非対応の形式の画像で会話が壊れる問題も直りました。現在は画像がディスクに保存され、ツールの結果からそのファイルを参照する形になります。

つまり、拡張子を .png に付け替えただけの画像は、形式の変換にはなりません。手元で確かめるときは、先頭のバイトを見る方法があります。PNGなら 89 50 4e 47、JPEGなら ff d8 ff で始まります。sips -g format が format: png と答えるかどうかも、同じ確認になります。

画像が失敗し続けるように見えたときの修正も、changelogに残っています。v2.1.166では、処理できない画像を送ったセッションで「image could not be processed」のエラーが繰り返され、トークン消費も増える問題が直りました。v2.1.172では、複数の画像がある会話で「画像が処理できず取り除かれた」という趣旨のエラーが繰り返される問題が直っています。同じエラーが何度も出るときは、更新が済んでいるかを先に見ます。

「Image was too large」とは原因が別

2つのエラーは、似たタイミングで出るので混同されがちです。違いは、問題が画像の中身にあるか、寸法にあるかです。

「Image was too large」は、処理できない画像をテキストのプレースホルダーに置き換えて再送するので、後続のメッセージは通ります。v2.1.142より前は、貼り付けた画像が会話に残り、以降のメッセージで毎回同じエラーが出ました。その版ではEscを2回押し、画像を足したターンより前まで戻って回復します。

両方に当たったときは、先に「Unable to resize image」の文言が指す形式の問題を解消し、その後で寸法を確かめます。「Image was too large」の原因と対処では、8000pxと2000pxが切り替わる条件を扱っています。エラーの種類を広く見たい場合はClaude Codeでよくあるエラー10選が入口になります。画像が積み重なった会話で出る「Request too large」の対処は、会話全体のサイズが原因なので別の手当てになります。画像が会話に溜まって32MBを超えると、Claude Codeは画像を外して再送します。手動で減らすなら、/compact で溜まった画像と添付を落とせます。v2.1.281では、ツールが大きすぎる画像を返したときに、並行するツール呼び出しが応答なしのまま残る問題も直っています。

画像処理まわりの修正は版ごとにどう動いたか

画像の失敗の扱いは、changelogで確認できるだけでも少しずつ変わってきました。

CMYK・アニメーションWebP・破損を名指しする5〜7つ目の文言は、v2.1.265のこの改善で入ったと読めます。v2.1.269以降はCMYKのJPEGが変換されるため、CMYKの文言に当たるのは主にそれより前の版です。エラー一覧には現在も例として残っています。

v2.1.265より前の版でこのエラーが続くときは、claude update で更新してから再度試します。

画像処理が失敗した後の壊れ方は、版を追うごとに穏やかになりました。多くは、失敗しても会話を巻き込まないための修正です。v2.1.269のCMYK変換のように、失敗そのものを減らす修正も入っています。ネイティブモジュールの失敗は画像だけの話でもありません。v2.1.70では、音声入力のネイティブモジュールがWindowsのネイティブバイナリで「native audio module could not be loaded」と読み込めない不具合が直っています。

Claude Code全体のインストール状態を調べるコマンドに、claude doctor があります。claude doctor --help の説明は次のとおりで、画像処理を個別に診断するとは書かれていません。

Check the health of your Claude Code installation. Reads settings files in the
current directory without a trust prompt. For a full checkup that can also fix
issues, run /doctor in a session.

まとめ

文言に原因が書かれていれば、その指示どおりに保存し直せば足ります。拡張子では分からない色空間は、sips -g space で確かめられます。更新で直る可能性が残る古いバージョンでは、まず claude update を試します。