Claude Media
Claude CodeがHyper-V仮想マシンで止まる原因 — 互換モードとAVXの確認手順
Claude CodeTips

Claude CodeがHyper-V仮想マシンで止まる原因 — 互換モードとAVXの確認手順

Hyper-V上のVMでClaude Codeのインストールや起動が止まる、またはIllegal instructionで落ちるときの原因です。互換モードとAVXの確認コマンド、切る手順を示します。

読了目安 約10分

Hyper-V上のClaude Codeが止まる2つのパターン

Hyper-VのVMでClaude Codeが動かないとき、症状は大きく2つに分かれます。どちらもCPUの見え方が原因ですが、見るべき設定が違います。

症状疑う設定報告されたissue
インストールも起動も出力なしで止まり、CPUが100%に張り付く疑う設定VMのProcessor Compatibility Mode(互換モード)報告されたissue#96237
Illegal instructionで落ちる(終了コード3)疑う設定ゲストにAVXが渡っていない報告されたissue#87060

どちらのissueもopenのままで、確定した修正バージョンはありません。ここでは、報告者が実際に確かめた切り分けと、手元で再現できる確認コマンドを順に並べます。

一般的な命令セット不一致(ARMサーバーにx86バイナリが入るなど)はIllegal instructionエラーの原因と対処にまとめています。ここで扱うのはHyper-V固有の設定です。

互換モードを有効にしたVMで無限に止まる(#96237)

報告された症状

Ubuntu Server 26.04 LTSのVMで、Hyper-Vホスト側がそのVMの「Processor Compatibility Mode」を有効にしていると、Claude Codeのネイティブバイナリとdebパッケージの両方が止まります。止まるのはinstallと対話起動の両方です。

このモードは、異なる世代のCPUが混在するプールでライブマイグレーションを通すために、CPUの機能を絞って見せる設定です。症状は次のとおりでした。

  • メインスレッドが1コアを100%使い続け、30分以上で33分超のCPU時間が積み上がった
  • 出力はなく、SIGINTにもきれいには応答しない
  • strace -f -pで観測すると、メインスレッドのシステムコールは観測期間を通じてゼロ
  • 他のスレッドは通常どおりfutex待ちを繰り返しており、止まっているのはメインスレッドだけ

報告者はこれを、待ちで止まるデッドロックではなく、ユーザー空間で回り続けるlivelockと整理しています。確認したバージョンは、apt版の2.1.267とネイティブインストーラー版の2.1.280で、どちらも同じように止まりました。

互換モードを切ると直る

報告者の検証では、対象VMで互換モードを無効にすると、installもclaudeも直ちに成功しました。ほかの変更は入れていません。再び有効にすると、また止まりました。

同じクラスタ内で、既存VMと新しく作ったVM(ホスト、ストレージ、ネットワークは同じ)の2台を試し、どちらも互換モードがオンで止まりオフで動いています。これで、変数は互換モードの1設定に絞られています。

ほかの原因候補は、報告者が次のように外しています。

  • EDR(SentinelOne)を完全に無効にしても変わらない
  • ローカルディスクで、ネットワークマウントではない
  • 古いロックファイルや残留プロセスを消しても変わらない
  • ゲストカーネルを上げても変わらない
  • 止まる前後でsocket()やconnect()が一度も呼ばれておらず、ネットワーク待ちではない
  • 世代は、止まるVMも動くVMもGen 2(UEFI、Secure Boot有効)

比較対象として、OpenAIのCodex CLI(Rust製のネイティブバイナリ)は、互換モードが有効なままの同じVMで起動したと報告されています。報告者は、カーネルやハイパーバイザー全体の問題ではなく、Claude Codeのランタイム(Bun)側に原因があると見ています。ただし、これは報告者の推測で、Anthropicからの原因の確認や修正のコメントはissue上にありません。

AVXが無いことは、止まる原因ではなかった

名前から「AVXを隠すから止まる」と考えたくなりますが、報告された比較はそうなっていません。報告者が並べた3つの状態は次のとおりです。

状態AVX・AVX2rdtscp・ssse3・sse4_1・sse4_2・popcnt結果
互換モードOFF(クラスタ)AVX・AVX2ありrdtscp・ssse3・sse4_1・sse4_2・popcntあり結果動く
互換モードON(単独ホスト)AVX・AVX2なしrdtscp・ssse3・sse4_1・sse4_2・popcntあり結果動く
互換モードON(クラスタ内ホスト)AVX・AVX2なしrdtscp・ssse3・sse4_1・sse4_2・popcntなし結果止まる

AVXが見えない点は、動く状態と止まる状態に共通しています。動作と停止を分けたのは、rdtscp、ssse3、sse4_1、sse4_2、popcntの5つがゲストに見えるかどうかでした。互換モードで隠れるCPU機能の範囲はホストごとに違い、AVXの有無だけを見ても結論を誤ります。

同じ設定でも、ホストで隠れ方が違う理由

報告者は、同じ互換モードでもマスクの中身が違う理由を、VMの構成バージョンで説明しています。Get-VM | Select ConfigurationVersionで確認すると、止まったHyper-V 2019のホストは構成バージョン9.0が上限で、動いたHyper-V 2022のホストは10.0でした。互換モードで隠れる範囲は構成バージョンに結びつき、それはホストのHyper-Vのビルドで決まる、という説明です。VM側や配置先では変えられません。

この関係はMicrosoftの文書で裏付けを取れた内容ではなく、報告者の分析です。自分の環境で試すなら、構成バージョンは手がかりの1つとして扱うのが無難です。

AVXが見えないVMでIllegal instructionになる(#87060)

もう1つのissueは、Windows 11上のClaude DesktopのCowork機能です。VM自体は約50秒で起動してAPIにつながりますが、セッションを始めるとClaude Codeのプロセスが終了コード3で落ちます。ログには次の行が出ていました。

panic: Illegal instruction at address 0x7FF6C80408D4
Claude Code process exited with code 3

報告者(Claude Code SDK 2.1.229)は、BunがAVXを使うのにHyper-VのVMがAVXを渡さないことが原因、と書いています。過去のissueを根拠に挙げていますが、肝心のCPU情報の欄は「ここに貼る」のプレースホルダのまま空で、このissue単体ではAVXが見えていなかったことまでは示されていません。コメントで別の利用者が「Hyper-VはAVXをゲストに渡さないのが既定」と書いていますが、これも根拠は添えられていません。

公式のトラブルシューティング文書は、AVX非対応の影響を「2013年より前のIntel・AMD製CPUと、ハイパーバイザーがAVXをゲストに渡さない仮想マシン」と書いています。確かめる方法はgrep -m1 -ow avx /proc/cpuinfoで、結果が空ならゲストにAVXは来ていません。CoworkのVMはClaude Desktopが管理するものなので、利用者がVMのCPU設定を直接触る手順は、このissueには載っていません。

ゲストとホストで確認するコマンド

ゲスト(Linux)側

まず、止まっているのか落ちているのかを分けます。timeoutが30秒で打ち切れば終了コードは124になり、Illegal instructionなら132(128にSIGILLの4を足した値)が返ります。

timeout 30 claude --help > /dev/null; echo "exit=$?"

次に、ゲストに見えているCPU機能のうち、ここまでの報告に出た7つを調べます。

grep -m1 '^flags' /proc/cpuinfo | tr ' ' '\n' \
  | grep -xE 'rdtscp|ssse3|sse4_1|sse4_2|popcnt|avx|avx2'

出力にavxが無いなら、#87060の型です。avxが無くてもsse4_2とpopcntまでは見えているなら、#96237の単独ホストの例(動いた側)に近い状態です。5つが全部欠けているなら、止まった側の状態です。

止まっている最中のプロセスは、スレッド単位のCPU使用率で見分けられます。

top -H -p "$(pgrep -n claude)"

メインスレッドだけが100%近く、ほかが0%なら、#96237と同じ形です。

ホスト(Hyper-V)側

互換モードの状態は、管理者権限のPowerShellで読めます。

Get-VMProcessor -VMName <VM名> |
  Select-Object CompatibilityForMigrationEnabled
Get-VM -Name <VM名> | Select-Object Name, ConfigurationVersion

CompatibilityForMigrationEnabledがTrueなら、互換モードが有効です。MicrosoftのSet-VMProcessorの説明では、このパラメーターは「別のホストへ移行するときの互換性のため、仮想プロセッサーの機能を制限するかどうか」を指定します。

互換モードを切る・切れないときの選択肢

互換モードの無効化は、同じコマンドで行います。

Set-VMProcessor -VMName <VM名> -CompatibilityForMigrationEnabled $false

Microsoftの例はTestVMを$trueにするものですが、値を$falseにすれば反対の操作になります。設定を変えたあとは、ゲストでClaude Codeを入れ直すか起動し直して、止まらないかを確かめます。

注意点は、この設定がライブマイグレーションのためにあることです。報告されたクラスタは、世代の違うCPUが混在するプールでした。互換モードを切ると、その間のライブマイグレーションに支障が出る可能性があります。クラスタ運用のVMでは、止まるVMだけを移行しない固定ホストに置くなど、運用側の判断が先に必要です。

切れない場合に、issue上で挙がっているのは次の2点だけです。

  • ホストのHyper-Vを新しい世代に上げる。報告者の観察では、2022のホスト(構成バージョン10.0)では互換モードがオンでも動いたが、これは因果の検証までは取れていない
  • コミュニティが作ったNode.js版のフォーク。AVXの無い環境向けにBunを使わず作り直したもので、作者自身が「アプリ本体のコードはv2.1.88前後で止まっている」と注記している。Anthropic公式のビルドではないため、導入は自己責任の範囲になる

Windows側のインストール手順そのものを見直したいときはClaude Code Windowsインストールも参照してください。Claude Desktopが裏でHyper-Vの仮想マシンを立てる仕組みは別の記事にあります。

切り分けの順番

手順

Hyper-V上でClaude Codeが動かないときの確認順

  1. 1

    止まりか、落ちかを分ける

    timeout 30 claude --helpの終了コードが124なら止まり、132ならIllegal instructionです。

  2. 2

    ゲストでCPU機能を見る

    /proc/cpuinfoのflagsで、avxとsse4_2、popcnt、ssse3、rdtscpの有無を確かめます。

  3. 3

    ホストで互換モードを見る

    Get-VMProcessorでCompatibilityForMigrationEnabledを読みます。Trueなら有効です。

  4. 4

    試せるなら互換モードを切る

    Set-VMProcessorで無効にし、再試行します。直れば原因は互換モードで、直らなければ別の要因を探します。

互換モードのVMで止まる場合も、AVXが無いVMで落ちる場合も、実行するバイナリが想定するCPU機能と、ゲストに見える機能のずれが出発点です。ゲストでgrepした結果と、ホストの設定値を突き合わせれば、どちらの型かは短時間で分かります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →