Illegal instructionエラーの原因と対処 — Claude Code

まず2つの原因を切り分ける

claudeコマンドやインストーラーが次のメッセージを出して止まる場合があります。

Illegal instruction

ネイティブバイナリが、実行中のCPUにない命令を使おうとして落ちた状態です。原因は2通りあり、直し方がまったく違います。

原因1 — アーキテクチャの取り違えを確かめる

macOSとLinuxでは次のコマンドで実行中のマシンの種類を確認します。

uname -m

Windowsでは、PowerShellで次の変数を見ます。

$env:PROCESSOR_ARCHITECTURE

手元のApple Silicon搭載Mac(Claude Code v2.1.287)で実行すると、次のように出ます。

uname -m
sysctl -n machdep.cpu.brand_string
claude --version

arm64
Apple M1 Pro
2.1.287 (Claude Code)

aarch64やarm64が返るのに取得したバイナリがx86向けだった、という食い違いがあれば原因1です。docsは、アーキテクチャが合わないときの手順としてissueでの報告だけを挙げています。uname -mの出力を添えてGitHubのissueに報告します。

対応するのはx64とARM64のプロセッサで、要件は4GB以上のRAMです。npm経由の対象はdarwin-arm64、darwin-x64、linux-x64、linux-arm64(各musl版を含む)、win32-x64、win32-arm64です。この一覧にない種類のCPUは、そもそも対象外になります。

原因2 — AVXが使えない環境を見分ける

アーキテクチャが合っているのに落ちるなら、CPUにAVXなど必要な命令が無い可能性が高くなります。バイナリの取り違えではなく、CPUが命令を持っていない問題です。

VPSや仮想マシンのLinuxでは、AVXがゲストから見えているかを次のコマンドで調べます。

grep -m1 -ow avx /proc/cpuinfo

何も出力されなければ、AVXはゲストに渡っていません。CPUモデルは次のコマンドで取れます。issueで報告するときはこの値を添えます。

grep -m1 "model name" /proc/cpuinfo

macOSには/proc/cpuinfoがありません。CPUモデル名はsysctl -n machdep.cpu.brand_stringで確認し、世代から判断します。

症状の出方は環境で変わる

メッセージの文言は環境ごとに違います。issue #50384には、報告ごとに次の出方が並んでいます。

• Docker内のDebian系Linux(AMD A4-3310MX): Illegal instruction
• Intel Mac mini(macOS): zshがillegal hardware instruction claudeと表示し、スタックトレースなしで終了
• Core 2 Duo搭載機のNixOS: Illegal instruction (core dumped)

macOSのzshでは「hardware」が入った別の文言になります。

Core 2 Duo P7550の報告では、sse4_2、popcnt、avxのどれも無いCPUでした。一方、AVXが無くてもSSE4.2までは持つ機種があります。Westmere世代のXeon X5675がその例で、issue #37065に報告があります。足りない命令はAVXだけとは限らず、docsも「AVXまたはほかの命令」と書いています。

AVXがあるのに落ちる、または止まるとき

grep -m1 -ow avx /proc/cpuinfoでavxが出るのに失敗するなら、別の命令が足りない可能性があります。issue #85571は、SSE4.2とPOPCNTの基準に届かないCPUでIllegal instructionが出た報告です。issue #95566では、kvm64というCPUモデルのVM(SSE4もPOPCNTも見えない)で、バイナリが何も出さずCPU使用率100%のまま止まっています。

SSE4.2、POPCNT、AVX2が見えているかは、次のコマンドで確かめられます。

grep -m1 -ow 'sse4_2\|popcnt\|avx2' /proc/cpuinfo

終了コードとカーネルログで見分ける

インストーラーが落ちた場合も、同じ原因で止まります。issue #96402には、Illegal instructionのあとに次の文言が出た報告があります。「Installation was killed before it could finish (exit code 132)」です。132は128にSIGILL(不正命令のシグナル、番号4)を足した値です。同じissueでは、--versionも落ちるため、CLI自身で診断や削除ができなかったとされています。

LinuxではカーネルログにCPUの例外が残ることがあります。次のコマンドでinvalid opcodeの行を探せます。

dmesg | grep -i 'invalid opcode'

回避策はあるのか — issue #50384の経緯

AVXの無いCPU向けのネイティブバイナリは用意されていません。npm・Homebrewなど別の方法でも、取得するのは同じネイティブバイナリです。

現在のv2.1系では、AVX非対応の扱いが何度か変わっています。changelogとissueを時系列に並べると次のとおりです。

その後も、AVXの無いCPUでの同じ失敗は別のissueに立っています。2026年9月23日のissue #96402は、AVXの無いベアメタルのLinuxでの報告です。ネイティブインストーラーのv2.1.280とnpm版のv2.1.197がどちらも落ち、JavaScriptバンドル最後のv2.1.112をNode 22で動かすと動きました。issue #90507はmacOS 12.7.6のv2.1.251での同様の失敗、issue #80443はSSE4.1より古いCPUに向けた低い基準のビルドを求める要望で、いずれも開いたままです。

トラブルシューティングのページは、状況の確認先としてissue #50384を挙げています。ただしissueはクローズされロックもされているため、困っている環境の情報を足したいときは、新しいissueを立ててissue #50384を参照する形になります。issueのロックにも「新しいissueを立てて、関連するなら参照してほしい」という案内が出ています。

issue上で報告されている回避策

次はissueのコメントで報告されているもので、Anthropicが案内する手順ではありません。

• v2.1.112に固定する: npm install -g @anthropic-ai/claude-code@2.1.112で入れ、自動更新を止めます。現行のdocsにある止め方は環境変数DISABLE_AUTOUPDATERを1にする方法で、settings.jsonのenvにも書けます。ただし止まるのはバックグラウンドの更新確認だけで、claude updateとclaude installは動きます。すべての更新経路を止めるならDISABLE_UPDATESを使います。
• 公式のnpmパッケージのcli.jsをNodeで動かす: issue #85571には、公式npm tarballのv2.1.108にあるcli.jsをnode cli.jsで動かした報告があります。加工しない方法ですが、非公式でサポート対象外です。認証情報を扱うプロセスになるため、自分で内容を確かめられる環境に限った話です。

issue #96402には、動いていたnpm版が自動更新でネイティブ版のラッパーに置き換わり、落ちるようになった報告があります。固定するときは、更新を止めてからバージョンを指定します。

第三者が公式配布物を加工してNodeで動かすスクリプトも別のissueに投稿されています。出所を確かめられない物を認証情報つきで動かすことになります。

v2.1.112に固定すると、v2.1.113以降の変更は受け取れません。v2.1.113のchangelogにはBashのdenyルールがラッパー付きコマンドにも効くようになる、find -execなどを自動承認しなくなる、といったセキュリティ項目が含まれます。固定すると、動かせる代わりに更新は止まります。

仮想マシンのAVX設定を見直す

物理CPUはAVXに対応しているのに、VMのゲストでgrepが空になる場合は、ハイパーバイザーがAVXを渡していないことが原因です。この場合に動かせるのはゲストOSではなく、ハイパーバイザー側のCPU設定です。設定名と画面は製品ごとに違います。

ゲストのCPU設定を変えて再起動したら、grep -m1 -ow avx /proc/cpuinfoを再実行して結果を見ます。それでも出なければ、ホストの物理CPUがAVXを持っていない可能性もあります。

マネージドVMを使うクラウドでは、ユーザーが触れる設定項目が限られます。VMを別のマシンタイプで作り直して同じgrepを試せば、AVXが見えるタイプかどうかを確かめられます。

似た症状で原因が違うエラー

Illegal instructionと見た目が近く、直し方が違うエラーがあります。トラブルシューティングのページが別項目として扱っているものを並べます。

macOSの要件は13.0以降、LinuxはUbuntu 20.04+・Debian 10+・Alpine 3.19+です。これより古いOSでdyld系のエラーが出た場合は、AVXではなくOSの世代を先に疑います。

よくある質問

Dockerコンテナの中でだけ出ます

コンテナはホストのCPUで動くため、ホストにAVXが無ければコンテナ内でも同じエラーになります。issue #50384の最初の報告も、AVXの無いCPUのホストで動かしたDockerコンテナでした。ベースイメージを変えても直りません。Docker環境での認証の持ち越しやヘッドレス実行はClaude Code Docker実行ガイドにまとめています。

WSLで出ます

Illegal instructionならAVX側の切り分けで、WSLのターミナル内でgrep -m1 -ow avx /proc/cpuinfoを実行します。cannot execute binary file: Exec format errorが出るならWSL1です。WSL 2は対応環境、WSL 1は対応外とされています。WSL固有のパスやNode.jsまわりの手順はClaude Code WSL2セットアップで扱っています。

まとめ

VMならまずハイパーバイザーのCPU設定を見直し、物理マシンでAVXが無いならv2.1.112への固定かAVXのあるマシンへの移行かを選ぶことになります。ほかのインストールエラーはClaude Codeインストールエラーの切り分けチェックリスト、全体像はClaude Code完全ガイドにあります。