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

「Illegal instruction」は2つの異なる原因で起きる

claudeコマンドやインストーラーの実行中に次のメッセージが出て強制終了する場合があります。

Illegal instruction

これはネイティブバイナリが、実行中のCPUがサポートしない命令セットを使おうとしたことを示すエラーです。原因は大きく2種類あり、どちらに当たっているかで対処がまったく違います。切り分けを誤ると無駄な作業を重ねることになるので、まず原因を特定してください。

原因1 — アーキテクチャの取り違え

インストーラーが実行環境と異なるアーキテクチャ向けのバイナリをダウンロードしてしまうケースです。典型的には、ARMサーバー上でx86向けバイナリを取得してしまうような状況で起こります。仮想化環境やクラウドのARMインスタンスで、インストールスクリプトの自動判定が実際のCPUアーキテクチャを正しく検出できなかった場合に発生します。

実行中のマシンのアーキテクチャは、macOSとLinuxでは次のコマンドで確認できます。

uname -m

Windowsでは、PowerShellで次の変数を確認します。

$env:PROCESSOR_ARCHITECTURE

uname -mがaarch64やarm64を返しているのに、取得されたバイナリがx86向けだったというような不一致が確認できたら、これがアーキテクチャの取り違えです。この場合は自分で修正する手段が用意されていないため、uname -m(またはWindowsの環境変数)の出力を添えてGitHub issue(github.com/anthropics/claude-code/issues)を報告してください。

原因2 — CPUがAVX命令セットを未サポート

アーキテクチャ自体は合っているのにIllegal instructionが出る場合は、CPUがAVX(Advanced Vector Extensions)など、ネイティブバイナリが要求する命令セットをサポートしていないことが原因です。原因1のようにダウンロードされたバイナリの取り違えではなく、CPU自体の命令セットの制約であるため、インストーラーやダウンロード元を変えても解決しません。

この現象が起きやすいのは主に2つの環境です。おおむね2013年より前に製造されたIntel・AMDのプロセッサと、ハイパーバイザーがAVXをゲストOSに渡していない仮想マシンです。物理的に古いマシンだけでなく、比較的新しいホスト上の仮想化環境でも、ハイパーバイザーの設定次第でゲスト側にAVXが見えないことがあります。

VPSや仮想マシン上で確認する場合は、次のコマンドでAVXがゲストから見えているかを確認できます。

grep -m1 -ow avx /proc/cpuinfo

このコマンドの結果が空(何も出力されない)であれば、AVXがゲスト環境に渡されていません。macOSでは/proc/cpuinfoは存在しないため、代わりにCPUモデル名から製造時期を推測する形になります。

sysctl -n machdep.cpu.brand_string

Linuxで同様にCPUモデル名を確認したい場合は次のコマンドを使います。

grep -m1 "model name" /proc/cpuinfo

AVX非対応のCPUには回避策が用意されていない

ここが他のインストールエラーと大きく異なる点です。PATHの設定ミスやネットワークの問題であれば別の方法で回避できますが、AVX非対応のCPU向けのネイティブバイナリは用意されていません。インストール方法をnpm経由に変えても、Homebrew経由に変えても、最終的にダウンロードされるのは同じネイティブバイナリです。インストーラーの種類を変える対処はこの原因には効きません。

この制約はissue #50384(github.com/anthropics/claude-code/issues/50384)で追跡されています。該当する環境で困っている場合は、上記のコマンドで取得したCPUモデル名(Linuxならmodel name、macOSならbrand_stringの値)を添えて、このissueにコメントする形で状況を共有できます。

仮想マシンでAVXを有効にできるか確認する

物理CPU自体はAVXに対応しているのに、仮想マシン側の設定でゲストにAVXが渡っていないケースでは、ハイパーバイザー側の設定変更で解決できる場合があります。VMwareやKVMなど主要なハイパーバイザーでは、CPU機能のパススルー設定やCPUモデルの指定(host-passthroughなど)によってゲストにAVXを見せられることがあります。クラウドプロバイダーのマネージドVMを使っている場合は、インスタンスタイプそのものがAVX非対応の世代である可能性もあるため、より新しい世代のインスタンスタイプへの変更が確実な解決策になることもあります。

自宅サーバーやオンプレミスのハイパーバイザーを自分で管理している場合は、ゲストのCPU設定を「ホストのCPU機能をそのまま渡す」設定に変更してから再起動し、grep -m1 -ow avx /proc/cpuinfoを再実行して確認してください。設定変更後もAVXが見えないままであれば、ハイパーバイザー自体のバージョンが古く、ホストのCPU機能を正しくエミュレートできていない可能性があります。

よくある質問

アーキテクチャの取り違えとAVX非対応、どちらが多い原因ですか

クラウド環境やコンテナが主流になったことで、アーキテクチャの取り違えはインストーラー側の判定改善で減ってきています。一方でAVX非対応は物理的なCPU世代やハイパーバイザーの設定に依存するため、古いVPSや小規模な仮想化基盤ではまだ一定数発生します。まずuname -mで自分の環境のアーキテクチャを確認し、取得したバイナリと矛盾がないかを最初に見るのが遠回りの少ない進め方です。

別のインストール方法(npm・Homebrewなど)に切り替えれば直りますか

直りません。インストール方法が違っても、最終的に配置されるのは同じプラットフォーム向けのネイティブバイナリです。npmパッケージ経由のインストールも、Homebrew経由のインストールも、内部では同じバイナリをダウンロードする仕組みのため、AVX非対応が原因の場合はどの方法を試しても同じIllegal instructionに行き着きます。

古いバージョンのClaude Codeに戻せば動きますか

バージョンによって要求する命令セットが変わっている可能性はありますが、公式に「このバージョン以前ならAVX不要」という明確な区切りは案内されていません。ダウングレードを試す前に、まずissue #50384(github.com/anthropics/claude-code/issues/50384)で対応状況を確認し、確実な情報がない状態での試行錯誤に時間をかけすぎないようにしてください。

仮想マシンでなく物理マシンでもこのエラーは起きますか

起きます。2013年より前に製造されたIntel・AMDのプロセッサは物理マシンであってもAVXをサポートしていないことがあります。該当する古いマシンでClaude Codeを動かしたい場合、CPUの買い替えか、AVXに対応した別のマシン・クラウド環境への移行以外に確実な回避策はありません。

Illegal instructionはインストール時と実行時のどちらで出ますか

どちらでも起こり得ます。インストーラー自体がネイティブバイナリを使って自己診断や展開処理を行う場合はインストール中に、インストールが完了した後にclaudeコマンドを実行したタイミングで出る場合は実行時に発生します。どちらのタイミングでも原因の切り分け方(アーキテクチャかAVXか)は同じです。

Dockerコンテナ内でこのエラーが出ます

コンテナのベースイメージが動作しているホストのCPUと異なるアーキテクチャ向けにビルドされている場合、コンテナ内でも同じIllegal instructionが起きます。docker run時にプラットフォームを明示的に指定していないか、マルチアーキテクチャ対応のベースイメージを使っているかを確認してください。AVX非対応が原因の場合は、コンテナの問題ではなくホスト側のCPU・ハイパーバイザーの制約なので、コンテナの構成を変えても解決しません。Docker環境でのClaude Codeの認証永続化やヘッドレス実行の設定はClaude Code Docker実行ガイドにまとめています。

WSL環境でも同じ2原因の切り分けになりますか

なります。WSL(Windows Subsystem for Linux)はLinux向けのインストールスクリプトを使うため、アーキテクチャ取り違えとAVX非対応のどちらも起こり得ます。WSL2ではホストのハードウェア仮想化機能を経由してゲストにCPU命令セットを渡す構成のため、ホストの物理CPUがAVXに対応していても、Hyper-Vの設定次第でゲスト側に渡らないケースがあります。grep -m1 -ow avx /proc/cpuinfoをWSL内のターミナルで実行して確認する手順は通常のLinux環境と同じです。WSL固有のパスやNode.jsまわりのつまずきはClaude Code WSL2セットアップで扱っています。

まとめ

Illegal instructionは、アーキテクチャの取り違えかAVX命令セットの非対応のどちらかが原因です。uname -mで取得したバイナリとの整合性を確認し、一致していなければアーキテクチャの取り違えとしてGitHub issue(github.com/anthropics/claude-code/issues)へ報告します。一致している場合はgrep -m1 -ow avx /proc/cpuinfoでAVXの有無を確認し、非対応であれば確実な回避策は無く、issue #50384(github.com/anthropics/claude-code/issues/50384)の状況を追う形になります。他のインストールエラーの切り分けはClaude Codeインストールエラーの切り分けチェックリストにまとめています。