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

「Unable to resize image」は、画像が大きすぎることそのものではなく、Claude Code側の画像処理が動かなかったことが原因のエラーです。Claude Codeは通常、上限を超えた画像を自動で縮小してからAPIに送りますが、この縮小処理を担う仕組みが読み込めなかったりエラーを返したりすると、縮小前の画像がそのまま送信できずに止まります。似た文言の「Image was too large」と混同されがちですが、原因も対処も別物です。

Unable to resize imageとは

Claude Codeは画像処理を担う専用のモジュールを内部に持ち、必要になった最初のタイミングで読み込みます。このモジュールが正しく起動できないと、画像の縦横サイズを読み取ることも、上限に合わせて縮小することもできなくなります。エラーメッセージが「resize」という単語を含んでいるのは、原因が画像そのものではなく縮小処理という工程の失敗だからです。

このエラーが「Image was too large」と根本的に違うのは、画像が正常な状態でも起きる点です。「Image was too large」は画像そのものの寸法が上限を超えているときに出ますが、「Unable to resize image」は上限内に収まるはずの画像でも、縮小処理を担うモジュール側の不調が原因で失敗します。

公式のエラー説明は「処理モジュールが読み込めなかった、またはエラーを返した」という結果だけを述べており、具体的な原因までは特定していません。実務上は、サンドボックス化された実行環境やコンテナ内の最小構成など、環境側の依存不足が背景にあることが多いと考えられます。Claude Codeにはこの種のネイティブモジュールが画像以外にも存在し、たとえば音声入力モジュールがWindows環境で読み込めず「native audio module could not be loaded」と失敗する不具合が過去にありました。ネイティブモジュールがOSやCPUアーキテクチャの組み合わせによって読み込みに失敗する、という同じ種類の失敗パターンです。

4つのメッセージパターンと原因の切り分け

実際に表示される文言は4パターンあり、どれに当たったかで疑うべき原因が変わります。

1番目のパターンは、対応形式(PNG・JPEG・GIF・WebP)以外のファイルを貼ったときにも起きやすいメッセージです。Claude Codeはこれらの主要形式であれば、画像処理モジュールを介さずに寸法を確認できるため、まず形式を疑う価値があります。HEICやTIFF、BMPなど、スクリーンショットツールやスマートフォンが標準で書き出す形式の一部はここに含まれません。

2番目と4番目は、どちらも2000×2000pxという基準に触れていますが意味が違います。2番目は「上限を超えていることは判明したが縮小できない」状態、4番目は「上限内かどうかそもそも判定できない」状態です。後者のほうが画像処理モジュールの不調が根深いケースで、形式変換だけでは直らないことが多くなります。

3番目のraw・base64を挙げるパターンは、変換後のデータサイズを圧縮で削ろうとして、その圧縮処理自体が失敗した状態を示します。縮小と圧縮の両方が機能していないため、4パターンの中でもっとも重い部類です。

対処法: 画像形式の変換から手動リサイズまで

メッセージが形式の変換を促している場合は、PNG・JPEG・GIF・WebPのいずれかに変換してから貼り直します。これらの形式ならClaude Codeが画像処理モジュールを介さずに寸法を確認できるため、モジュール側の不調があっても影響を受けません。

magick input.heic output.png

メッセージが寸法や上限を具体的に示している場合は、手動でリサイズしてから貼り直します。2000×2000pxという基準が出ているときは、macOSならsipsで長辺を指定します。

sips -Z 2000 input.png --out output.png

貼り付け以外の経路、たとえばファイルパスを指定してClaude Codeに画像を読み込ませる場面でも、同じ画像処理モジュールが使われます。貼り付けを避けても解消しない場合は、モジュール側の問題を疑います。

原因の切り分けに迷ったら、claude doctorでインストール状態を確認しておきます。読み取り専用の診断コマンドで、環境まわりの不整合を洗い出せます。

claude doctor

画像処理モジュールにまつわる過去の不具合

このエラーの背景にある「画像処理モジュール」は、v2.1.71で起動タイミングが見直されています。それ以前は起動時に毎回読み込んでいたモジュールを、実際に画像が必要になった最初のタイミングまで遅らせる変更です。この変更自体は起動速度の改善が目的でしたが、結果として画像処理モジュールの不調は「画像を初めて扱ったとき」に集中して表面化するようになりました。

同じv2.1.71では、Read toolが画像を開こうとして画像処理に失敗したとき、縮小前の巨大な画像データがそのまま会話の文脈に残ってしまい、以降のやり取りが壊れる不具合も修正されています。ペーストではなくファイル読み込み経由でもこの種の失敗が起こり得ることを示す実例です。SDK経由の利用でも同様の設計思想があり、v2.1.113では画像コンテンツブロックの処理に失敗したときにセッション全体がクラッシュする不具合を修正し、テキストのプレースホルダーへ穏やかに縮退するよう変わりました。

いずれの修正にも共通しているのは、「画像処理が失敗したときにどう壊れるか」を段階的に穏やかにしてきた経緯です。失敗そのものをゼロにする改修ではなく、失敗したときに会話全体を巻き込まないようにする方向で改善が積み重ねられています。逆に言えば、画像処理そのものが動かない環境的な原因(コンテナの依存不足など)は、バージョンを上げるだけでは解消しないことがあります。

Image was too largeとの違い

同じ画面で似たタイミングに出る「Image was too large」は、画像の寸法そのものが上限を超えているときのエラーです。こちらは寸法が正常でも処理の仕組み側が動かないときに出ます。両方に当たった場合は、まず本記事の対処(形式変換・手動リサイズ)を試し、それでも直らなければ「Image was too large」の原因と対処で寸法の上限そのものを確認します。エラーの種類を一覧で確認したい場合はClaude Codeでよくあるエラー10選も参考になります。似た場面で発生しやすい「Request too large」の対処も、画像を多く扱うセッションでは合わせて押さえておくと切り分けが速くなります。

よくある質問

対応形式に変換しても直りませんか

直らない場合は、画像処理モジュール自体に問題がある可能性が高いパターンです。寸法や上限を示すメッセージに変わっていないか確認し、変わっていれば手動リサイズを試します。それでも同じエラーが出続けるなら、Claude Codeの再インストールを検討します。

既存ファイルを貼っても同じエラーが出ます

貼り付け方法(クリップボード・ドラッグ&ドロップ・ファイル参照)にかかわらず、同じ画像処理モジュールが使われます。特定の貼り付け方法だけの問題ではないため、まず形式変換とリサイズの両方を試します。

どちらのエラーを先に疑うべきですか

画像が明らかに大きい(高解像度スクリーンショットや書き出したままのデザインファイルなど)場合は、まず寸法超過を疑い本記事の手動リサイズを試します。逆に、普段問題なく貼れているはずの小さな画像でも起きる場合は、画像処理モジュール側の不調を疑います。

コンテナやCI環境で起きやすいですか

最小構成のコンテナイメージでは、画像処理に必要なネイティブ依存が入っていないことがあり、通常のデスクトップ環境より起きやすい傾向があります。ベースイメージを最小限に削ったDockerfileほど、こうした周辺ライブラリが最初から欠けがちです。画像を扱う可能性がある自動化パイプラインでは、claude doctorを起動時のヘルスチェックに組み込んでおくと早期に気づけます。

まとめ

「Unable to resize image」は、画像そのものではなくClaude Code側の縮小処理が動かなかったことが原因です。メッセージが形式変換を促しているならPNG・JPEG・GIF・WebPへの変換、寸法や上限を示しているなら手動リサイズ、どちらを試しても直らないなら再インストールという順で切り分けると、無駄な試行を減らせます。同じ画面に出るエラーでも原因は一枚岩ではないので、まずどのメッセージパターンかを確認するところから始めます。開発環境を移したばかりのタイミングでこのエラーに当たったときは、環境側の依存不足を真っ先に疑う価値があります。