VS Codeの「Unable to resolve workspace folder」エラーの解決方法

問題の概要

VS Codeが突然プロジェクトフォルダを読み込まなくなったという、イライラする問題に遭遇しました。サイドバーにファイルが表示される代わりに、「Unable to resolve workspace folder（ワークスペースフォルダを解決できません）」という通知が表示されます。これは通常、マルチルートワークスペースまたは .code-workspace ファイルを使用している場合に、VS Codeが構成で定義されたディレクトリのいずれかを見つけられなくなったときに発生します。

このエラーは、ハードドライブ上でフォルダを移動したり、親ディレクトリの名前を変更したり、あるいはまだ接続されていない外付けドライブやネットワークマウントに保存されているプロジェクトファイルを扱っている場合に特によく発生します。

なぜこれが発生するのか

VS Codeでワークスペースを保存すると、.code-workspace という拡張子のJSONファイルが作成されます。このファイルには、プロジェクトフォルダへの絶対パスまたは相対パスが含まれています。これらのパスのいずれかが無効になると、VS Codeは空の環境や壊れた環境を表示したくないため、Unable to resolve workspace folder エラーをスローします。

一般的な原因：

VS Code以外でプロジェクトフォルダの名前を変更した。
.code-workspace ファイルを別のディレクトリ階層に移動した。
ネットワークドライブがアンマウントされている、またはUSBストレージが取り外されている。
マルチルート構成の一部だったフォルダを削除した。

ステップバイステップの解決策

1. .code-workspace ファイルを手動で編集する

これを解決する最も早い方法は、ソースを直接修正することです。ワークスペースファイル自体をまだ開ける場合はそうしてください。開けない場合は、ファイルエクスプローラーで見つけ、テキストエディタ（メモ帳やVimでも可）で開きます。

{
    "folders": [
        {
            "path": "frontend"
        },
        {
            "path": "../backend-api"
        },
        {
            "name": "Docs",
            "path": "/Users/dev/documents/project-notes"
        }
    ],
    "settings": {}
}

path の値を確認してください。それらのディレクトリが実際にその場所に存在するかチェックします。バックエンドフォルダを移動した場合は、ここでパスを更新します。Windowsを使用している場合は、ドライブ文字（例：D:）が正しいことを確認してください。

2. 絶対パスの代わりに相対パスを使用する

絶対パス（C:\Users\Admin\Project など）を使用すると、ワークスペースファイルをチームメイトと共有したり、別のマシンに移動したりした際にトラブルの元になることがわかりました。可能な限り相対パスに切り替えてください。

.code-workspace ファイルがプロジェクトのルートにある場合、パスは次のようになります。

"folders": [
    {
        "path": "."
    },
    {
        "path": "packages/api"
    }
]

3. フォルダを削除して再追加する

JSONの編集が難しく感じる場合は、VS CodeのUIから修正できます（ウィンドウが開いたままの場合）：

エクスプローラーのサイドペインで、壊れたフォルダ（通常は小さな「x」や警告アイコンが付いています）を右クリックします。
Remove Folder from Workspace（ワークスペースからフォルダを削除）を選択します。
File > Add Folder to Workspace...（ファイル > ワークスペースにフォルダを追加...）に進み、そのフォルダの新しい場所に移動します。
ワークスペースを再度保存します（File > Save Workspace As...）。

4. ネットワークと外部マウントを確認する

LinuxやmacOSでは、DockerボリュームやNFSマウントがアクティブでないときにこのエラーがよく見られます。ワークスペースのパスが /mnt/data/projects を指している場合、ターミナルで簡単なチェックを実行してください。

ls /mnt/data/projects

もし "No such file or directory" エラーが表示される場合は、VS Codeがワークスペースフォルダを解決できるようになる前に、ドライブを再マウントする必要があります。

5. VS Codeのワークスペースストレージをクリアする

VS Codeが、もはや存在しないワークスペースのキャッシュバージョンに固執してしまうことがあります。.code-workspace ファイルを削除したにもかかわらず、起動時にVS Codeがそれを開こうとし続ける場合は、内部状態をクリアする必要があるかもしれません。

VS Codeのグローバルストレージフォルダに移動し、workspaceStorage ディレクトリを探します。中にあるフォルダを削除してみてください（警告：これにより、そのプロジェクトの開いているタブやウィンドウサイズなどのUI状態がリセットされます）。

Windows: %APPDATA%\Code\User\workspaceStorage\
macOS: ~/Library/Application Support/Code/User/workspaceStorage/
Linux: ~/.config/Code/User/workspaceStorage/

修正の確認

パスを更新したりドライブを再マウントしたりしたら、すべてが正常に戻ったかどうかを以下の手順で確認します。

すべてのVS Codeインスタンスを閉じます。
ターミナルを開き、code path/to/your/project.code-workspace と入力します。
エクスプローラーのサイドバー（Ctrl+Shift+E または Cmd+Shift+E）を確認します。すべてのフォルダがエラーアイコンなしで展開されているはずです。
「ファイルを検索」（Ctrl+Shift+F）を実行してみます。すべてのフォルダから結果が返ってくれば、ワークスペースの解決は完全に機能しています。

パスの問題を防止するためのヒント

ローカルに保つ: シンプルな相対パスを使用できるように、マルチルートワークスペース内のすべてのフォルダを同じ親ディレクトリの下に置くようにしてください。
Git ignore: 特定のマシンのセットアップのために絶対パスを使用する場合は、同僚の環境を壊さないように、*.code-workspace ファイルを .gitignore に追加してください。
シンボリックリンクを使用する: どうしても特殊な場所にフォルダを置く必要がある場合は、メインのプロジェクトフォルダ内に外部の場所を指すシンボリックリンクを作成してください。VS Codeは、壊れたワークスペース定義よりもシンボリックリンクをはるかによく処理します。