Claude Media
Claude Codeが仮想ワークスペースでlibcエラーになる原因(VS Code拡張)
Claude Codeチュートリアル

Claude Codeが仮想ワークスペースでlibcエラーになる原因(VS Code拡張)

VS Code拡張が「native binary failed to launch」とlibcの不一致を示すのに、実際はバイナリが無関係なことがあります。仮想ワークスペースが原因かを見分ける手順と対処です。

読了目安 約12分

Claude Codeが仮想ワークスペースでlibcエラーになる原因(VS Code拡張)

「Claude Code native binary ... exists but failed to launch」と表示され、メッセージがglibcやmuslの不一致を示しているのに、claude.exe --version を単体で実行すると正常に動く。この食い違いが出たら、バイナリではなく、VS Codeで開いているワークスペースを疑う価値があります。

libcのメッセージが見当違いになるケース

GitHubのissue #96525は、VS Code拡張が仮想ワークスペースで起動したときの誤解を招くエラーを報告しています。仮想ワークスペースとは、ローカルのディスク上にフォルダを持たないワークスペースのことです。報告者が見たエラーは次の文面でした。

ReferenceError: Claude Code native binary at ...\native-binary\claude.exe exists
but failed to launch. This usually means the binary does not match this system's
libc — e.g. spawning a musl-linked binary on a glibc Linux host fails because the
musl dynamic loader (/lib/ld-musl-*) is missing. Specify a matching binary with
options.pathToClaudeCodeExecutable.

報告者の環境はWindows 11で、拡張のバージョンは2.1.281です。Windowsにはglibcもmuslもありません。それでも文面はLinuxのlibc不一致を前提にしています。つまりこのメッセージは「起動に失敗した」という事実しか伝えておらず、後半の原因説明は当てになりません。

issueの項目欄では、プラットフォームがAWS Bedrock、OSがWindowsとされています。同じissueには、macOS(arm64)のバージョン2.1.283でも同じ問題だという確認コメントがあります。

報告者はGitLab Workflow拡張の「Open Remote Repository」でリポジトリをクローンせずに開き、その新しいウィンドウでClaude Codeのパネルがこのエラーを出したと書いています。通常のローカルフォルダのウィンドウでは正常に動き、同じ claude.exe を単体で実行しても終了コード0で起動したとのことです。

失敗の仕組み: file:スキームの作業ディレクトリが無い

issueが示す根本原因は2点です。

  1. 拡張の package.json に capabilities.virtualWorkspaces の宣言が無く、VS Codeが仮想ワークスペース対応済みとみなして起動時に有効化する
  2. ネイティブバイナリには file: スキームの実在するローカルの作業ディレクトリが必要だが、仮想ワークスペースのルートは file: 以外のURIなので、起動に失敗する

2点目は、VS Code側の仕様と整合します。VS Codeの拡張ガイドによると、仮想ワークスペースでは、リソースがファイルシステムプロバイダー経由で提供され、URIのスキームが file とは限りません。例として vscode-vfs://github/microsoft/vscode/package.json のような形が挙げられています。ガイドは拡張作者に「URIのスキームが file だと決めつけない」ことを求めています。外部の実行ファイルを動かす拡張は、作業ディレクトリに使える実パスが無いという状況に必ず当たります。

1点目も、ガイドの記述どおりです。virtualWorkspaces を宣言していない拡張は、既定で true(対応済み)として扱われます。作者が supported: false を宣言して初めて、VS Codeは仮想ワークスペースでその拡張を有効にしません。issueはまさにこの宣言が無いことを突いています。

仮想ワークスペースになる開き方の例

VS Codeのガイドは、GitHub Repositories拡張の「Open GitHub Repository...」で仮想ワークスペースのウィンドウが開くと説明しています。issueはこれに加え、組み込みのRemote Repositoriesやgithub.dev、GitLab Workflow拡張のリモートリポジトリを例に挙げています。issueのコメントには、ABAPのリポジトリ(abap:/repotree-v1/...)を開いたウィンドウで同じ症状が出た例もあります。ディスク上のフォルダではなく、拡張が提供する独自スキームのツリーです。

自分の環境が該当するかを見分ける

libc不一致の疑いを晴らすには、次の3つを順に確認します。

1. ウィンドウが仮想ワークスペースかを見る

VS Codeは、仮想ワークスペースが開いているとき、左下のリモートインジケーターにラベルを表示します(VS Codeの拡張ガイドの説明)。ローカルフォルダのウィンドウにはこのラベルが付きません。ラベルがあり、開いているのがリモートのリポジトリなら、ディスク上のフォルダではありません。

2. 通常のローカルフォルダのウィンドウで試す

同じマシン、同じ拡張のバージョンで、ディスク上の普通のフォルダを開いたウィンドウを用意します。そこでClaude Codeのパネルが正常に動くなら、バイナリは壊れていません。起動に失敗するのは、ウィンドウ側の条件です。

3. バイナリを単体で動かす

エラー文に出ている native-binary の claude.exe(Linux・macOSなら対応するバイナリ)を、ターミナルから直接実行します。

& "<エラー文に出たパス>\native-binary\claude.exe" --version

バージョンが表示されれば、ファイルは存在し、このマシンで実行できています。libcの不一致なら、単体実行でも失敗するはずです。

3つの結果を並べると、原因は次のように分かれます。

確認結果疑うべき原因次の一手
仮想ワークスペースだけで失敗。ローカルフォルダでは動く疑うべき原因仮想ワークスペースでの起動次の一手ローカルフォルダを開く
どのウィンドウでも失敗。単体実行も失敗(Linux)疑うべき原因glibcとmuslの取り違えなど次の一手libcの判定と再取得
どのウィンドウでも失敗。バイナリが見つからない疑うべき原因インストール不備次の一手バイナリの再インストール

2行目と3行目の対処は、既存の記事で詳しく扱っています。Linuxで実行時に共有ライブラリが見つからない場合は、libstdc++.so.6エラーの原因と対処が判定コマンドを示しています。バイナリそのものが入っていないときは、native binary not installedエラーの対処を見てください。起動直後にクラッシュする別の症状は、SIGSEGVで落ちる原因が扱っています。

対処: ローカルのフォルダを開く

issueの時点で、報告者が確認している回避策は、仮想ワークスペースのウィンドウでClaude Codeのタブを閉じることだけです。使いたい場合は、ローカルのフォルダを開き直します。issueのコメントでも、次の手順が案内されています。

  1. FileメニューからOpen Folder... を選ぶ
  2. ディスク上の通常のフォルダを選ぶ(プロジェクトのフォルダがあればそれが望ましい)
  3. VS Codeが再読み込みされたら、Claude Codeのパネルを開いてログインする

リモートリポジトリで作業したい場合は、先にローカルへクローンしてから、そのフォルダを開く流れになります。

ただし、issueのコメントで報告者が指摘するとおり、これは根本解決ではありません。新しい仮想ワークスペースのウィンドウを開くたびに、拡張は自動で有効化されて同じエラーを出します。issueが求める修正は、拡張側で virtualWorkspaces を明示することです。

"capabilities": {
  "virtualWorkspaces": {
    "supported": false,
    "description": "Claude Code requires a local workspace."
  }
}

VS Codeの拡張ガイドの supported: false の例と同じ形式です。宣言されれば、VS Codeは仮想ワークスペースで拡張を自動で無効にし、標準のバッジを表示できる、というのがissueの主張です。issueには "limited" を選ぶ案も添えられています。issueには修正バージョンの記載が無く、直るまでは上の手順が実質的な回避になります。

切り分けでつまずきやすい点

「Restricted Mode」とは別の話

Claude Codeの公式ドキュメントは、Sparkアイコンが見えない原因の一つとして、拡張がRestricted Modeでは動かないことを挙げています。Restricted Modeは、ワークスペースを信頼していないときに入るモードです。信頼していないローカルフォルダで起きる問題と、仮想ワークスペースでの起動失敗は別の現象です。両方が同時に起きることもあるので、片方を直したあとにもう一度確認します。

拡張を入れ直しても直らない

バイナリは壊れていないため、再インストールで直る見込みは薄いはずです。issueでも、同じ症状が拡張のバージョン2.1.281とmacOS(arm64)の2.1.283で確認されており、OSやバージョンを変えても、仮想ワークスペースなら再現しています。

エラー文の pathToClaudeCodeExecutable に飛びつかない

メッセージは別のバイナリを指定するよう勧めますが、仮想ワークスペースが原因なら、バイナリを替えても、作業ディレクトリが無い状況は変わらないと考えられます。Claude Codeの拡張設定には claudeProcessWrapper があり、起動に使う実行ファイルを差し替えられます。これは、拡張のビルドに自分のプラットフォーム向けのバイナリが含まれないときの設定で、この問題の回避策としては書かれていません。

拡張を作る側が見るべきこと

この症状は、VS Code拡張の一般的な落とし穴でもあります。外部プロセスを cwd 付きで起動する拡張を作るなら、起動前にワークスペースが仮想かを判定できます。VS Codeの拡張ガイドが示す判定コードは次のとおりです。

const isVirtualWorkspace =
  workspace.workspaceFolders &&
  workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');

すべてのワークスペースフォルダが file 以外のスキームなら仮想ワークスペースです。コマンドやビューは、when 句の virtualWorkspace コンテキストキーで出し分けられます。Claude CodeでVS Code拡張を自作する手順で雛形を作る場合も、package.json の capabilities を最初に決めておくと、同種のエラーを避けられます。

まとめ

libcのメッセージが出ても、まずバイナリを疑う必要はありません。ウィンドウが仮想ワークスペースか、ローカルフォルダのウィンドウなら動くか、バイナリが単体で動くか。この3点で、原因は切り分けられます。仮想ワークスペースだけで失敗するなら、ローカルのフォルダを開けば回避できます。拡張側の修正までは、仮想ワークスペースのウィンドウでは毎回同じエラーが出ます。応答しない症状の一般的な切り分けは、VS Code拡張が応答しないときの手順にまとめています。

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

関連する記事

Claude Code をもっと見る →