VSCode トラブルシューティング完全ガイド - よくあるエラーと解決方法

VSCode トラブルシューティングで問題を迅速に解決する

Visual Studio Code（VSCode）は世界中の開発者に愛用される軽量エディタですが、拡張機能の競合やキャッシュの破損などにより、予期しない動作が発生することがあります。本記事では、VSCode トラブルシューティングの基本から応用まで、体系的に問題を切り分けて解決する方法を解説します。

エラーメッセージの読み方、ログの確認方法、拡張機能のBisect機能、Safe Mode起動、キャッシュクリア、完全な再インストール手順まで、初心者でも実践できる内容を網羅しています。

この記事で得られること

• 問題の原因を特定するための診断フローチャート
• Extension Bisectを使った拡張機能競合の切り分け方法
• Safe Mode（拡張機能無効）での起動手順
• ログファイルの確認と読み解き方
• 設定のリセットとキャッシュクリアの手順
• 完全なクリーンインストールの実施方法
• よくあるエラーメッセージと対処法

前提条件と実行環境

VSCode トラブルシューティングを実施するための前提条件を確認します。

トラブルシューティングの診断フローチャート

問題が発生した際は、以下のフローチャートに従って原因を切り分けます。体系的なアプローチにより、効率的に問題を特定できます。

flowchart TD
    A[VSCodeで問題発生] --> B{拡張機能を無効にして改善?}
    B -->|改善| C[Extension Bisectで問題の拡張機能を特定]
    B -->|改善しない| D{設定をリセットして改善?}
    D -->|改善| E[問題のある設定を特定]
    D -->|改善しない| F{キャッシュクリアで改善?}
    F -->|改善| G[キャッシュ破損が原因]
    F -->|改善しない| H[クリーンインストールを実施]
    
    C --> I[拡張機能の更新/アンインストール]
    E --> J[設定の段階的な復元]
    G --> K[解決]
    H --> K
    I --> K
    J --> K

拡張機能を無効にして起動する（Safe Mode）

多くのVSCode問題は拡張機能に起因します。すべての拡張機能を無効にした状態で起動することで、問題が拡張機能由来かどうかを判断できます。

コマンドラインから拡張機能を無効にして起動

ターミナルまたはコマンドプロンプトから以下のコマンドを実行します。

1
2
3
4
5

# すべての拡張機能を無効にして起動
code --disable-extensions

# 特定のフォルダを開きつつ拡張機能を無効化
code --disable-extensions /path/to/project

期待される結果

GUI から拡張機能を一括無効化

コマンドラインを使用しない場合は、以下の手順で一括無効化できます。

1. Ctrl+Shift+Xで拡張機能ビューを開く
2. 右上の...メニューをクリック
3. 「Disable All Installed Extensions」を選択
4. VSCodeを再起動

Extension Bisectで問題の拡張機能を特定する

拡張機能が原因と判明した場合、Extension Bisect機能を使って問題の拡張機能を二分探索法で効率的に特定します。

Extension Bisectの起動手順

1. Ctrl+Shift+Pでコマンドパレットを開く
2. 「Help: Start Extension Bisect」と入力して実行
3. 画面の指示に従って「Good now」または「This is bad」を選択

sequenceDiagram
    participant U as ユーザー
    participant V as VSCode
    participant E as 拡張機能群

    U->>V: Extension Bisect開始
    V->>E: 半分の拡張機能を無効化
    V->>U: 問題は解消しましたか?
    U->>V: Good now / This is bad
    V->>E: 探索範囲を半分に絞り込み
    Note over V,E: 繰り返し（log2(N)回）
    V->>U: 問題の拡張機能を特定

Bisectの計算量

Extension Bisectは二分探索アルゴリズムを採用しています。

従来の1つずつ無効化する方法と比較して、大幅に効率化されています。

問題の拡張機能が特定された後の対応

1. 拡張機能の更新を確認: 最新バージョンで修正されている可能性
2. 拡張機能をアンインストール: Ctrl+Shift+Xから歯車アイコン→「Uninstall」
3. Issue報告: 拡張機能のGitHubリポジトリに問題を報告

1
2
3
4
5

# コマンドラインから拡張機能をアンインストール
code --uninstall-extension publisher.extension-name

# インストール済み拡張機能の一覧を表示
code --list-extensions

VSCodeのログを確認する

問題の詳細を把握するには、ログファイルの確認が有効です。VSCodeは複数のログを出力しており、状況に応じて適切なログを参照します。

Developer Toolsでリアルタイムログを確認

1. Ctrl+Shift+Pでコマンドパレットを開く
2. 「Developer: Toggle Developer Tools」と入力して実行
3. 「Console」タブでエラーや警告を確認

出力パネルでのログ確認

1. Ctrl+Shift+Uで出力パネルを開く
2. ドロップダウンから確認したいログを選択
   • Log (Main): メインプロセスのログ
   • Log (Extension Host): 拡張機能ホストのログ
   • Log (Window): ウィンドウプロセスのログ

Verbose（詳細）モードでの起動

より詳細なログを取得する場合は、Verboseモードで起動します。

1
2
3
4
5

# Verboseモードで起動（詳細ログを出力）
code --verbose

# ログをファイルに出力
code --verbose --log trace 2>&1 | tee vscode-debug.log

ログファイルの保存場所

設定をリセットする

設定ファイルの破損や誤った設定値が問題の原因となることがあります。

設定ファイルの場所

設定を完全にリセットする手順

1. VSCodeを終了する
2. 設定ファイルのバックアップを作成

1
2
3
4
5

# Windows（PowerShell）
Copy-Item "$env:APPDATA\Code\User\settings.json" "$env:APPDATA\Code\User\settings.json.backup"

# macOS / Linux
cp "$HOME/.config/Code/User/settings.json" "$HOME/.config/Code/User/settings.json.backup"

3. settings.jsonの内容を空のオブジェクトに置き換え

1

{}

4. VSCodeを再起動

個別の設定をリセットする

Settings Editor（Ctrl+,）から個別の設定をリセットできます。

1. 設定エディタを開く（Ctrl+,）
2. リセットしたい設定を検索
3. 設定の横にある歯車アイコンをクリック
4. 「Reset Setting」を選択

変更された設定を確認する

1
2

# Settings Editorの検索ボックスに入力
@modified

これにより、デフォルト値から変更されたすべての設定が一覧表示されます。

キャッシュをクリアする

キャッシュの破損は、予期しない動作やクラッシュの原因となります。

キャッシュフォルダの場所

キャッシュクリアの手順

1. VSCodeを完全に終了する（タスクマネージャーでプロセスを確認）
2. キャッシュフォルダを削除

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# Windows（PowerShell）
Remove-Item -Recurse -Force "$env:APPDATA\Code\Cache"
Remove-Item -Recurse -Force "$env:APPDATA\Code\CachedData"
Remove-Item -Recurse -Force "$env:APPDATA\Code\CachedExtensions"
Remove-Item -Recurse -Force "$env:APPDATA\Code\CachedExtensionVSIXs"

# macOS
rm -rf "$HOME/Library/Application Support/Code/Cache"
rm -rf "$HOME/Library/Application Support/Code/CachedData"
rm -rf "$HOME/Library/Application Support/Code/CachedExtensions"
rm -rf "$HOME/Library/Application Support/Code/CachedExtensionVSIXs"

# Linux
rm -rf "$HOME/.config/Code/Cache"
rm -rf "$HOME/.config/Code/CachedData"
rm -rf "$HOME/.config/Code/CachedExtensions"
rm -rf "$HOME/.config/Code/CachedExtensionVSIXs"

3. VSCodeを再起動

期待される結果

キャッシュクリア後、初回起動時は以下の動作が発生します。

• 起動が通常より少し遅くなる（キャッシュ再構築のため）
• 拡張機能の再読み込みが行われる
• IntelliSenseのインデックスが再構築される

完全なクリーンインストールを実施する

上記の対処法で解決しない場合は、VSCodeの完全なクリーンインストールを実施します。

クリーンアンインストールの手順

Windows

1. コントロールパネルまたは設定からVSCodeをアンインストール
2. 以下のフォルダを削除

1
2
3
4
5

# ユーザーデータ
Remove-Item -Recurse -Force "$env:APPDATA\Code"

# 拡張機能
Remove-Item -Recurse -Force "$env:USERPROFILE\.vscode"

macOS

1. アプリケーションフォルダからVSCodeをゴミ箱に移動
2. 以下のフォルダを削除

1
2

rm -rf "$HOME/Library/Application Support/Code"
rm -rf "$HOME/.vscode"

Linux

1. パッケージマネージャーでVSCodeをアンインストール

1
2
3
4
5
6
7
8

# Debian/Ubuntu
sudo apt remove code

# Fedora
sudo dnf remove code

# RHEL/CentOS
sudo yum remove code

2. 以下のフォルダを削除

1
2

rm -rf "$HOME/.config/Code"
rm -rf "$HOME/.vscode"

再インストール

1. VSCode公式サイトから最新版をダウンロード
2. インストーラーを実行
3. 必要に応じて拡張機能を再インストール

起動時のパフォーマンス診断

VSCodeの起動が遅い場合、起動時間の詳細な計測と診断が可能です。

起動パフォーマンスの計測

1
2
3
4
5

# パフォーマンス計測モードで起動
code --status

# 詳細な起動パフォーマンスレポートを表示
code --performance

Developer: Startup Performanceコマンド

1. VSCodeを起動
2. Ctrl+Shift+Pでコマンドパレットを開く
3. 「Developer: Startup Performance」と入力して実行
4. 起動フェーズごとの所要時間が表示される

起動パフォーマンスレポートの読み方

extensionsフェーズが長い場合は、拡張機能の最適化を検討してください。

よくあるエラーメッセージと対処法

“Unable to write settings”

設定ファイルの書き込みに失敗するエラーです。

原因と対処法

1. settings.jsonの構文エラー

   • Ctrl+Shift+P → 「Preferences: Open User Settings (JSON)」
   • 赤い波線でエラー箇所を確認し修正

2. ファイルの権限問題

   • settings.jsonの書き込み権限を確認
   • 管理者権限でVSCodeを実行

“Extension host terminated unexpectedly”

拡張機能ホストプロセスがクラッシュするエラーです。

対処法

1. Extension Bisectで問題の拡張機能を特定
2. 拡張機能を最新バージョンに更新
3. 問題が解決しない場合はアンインストール

“Cannot install extension because Visual Studio Code cannot verify the extension signature”

拡張機能の署名検証に失敗するエラーです。

対処法

1. インターネット接続を確認
2. プロキシ設定を確認（企業ネットワークの場合）
3. 一時的に署名検証を無効化（非推奨）

1
2
3

{
  "extensions.verifySignature": false
}

“connect ETIMEDOUT” (拡張機能インストール時)

ネットワーク接続のタイムアウトエラーです。

対処法

1. インターネット接続を確認
2. プロキシ設定を追加

1
2
3
4

{
  "http.proxy": "http://proxy.example.com:8080",
  "http.proxyStrictSSL": false
}

“‘code’ is not recognized as an internal or external command”

codeコマンドがパスに登録されていない状態です。

対処法

• Windows/Linux: VSCodeを再インストール
• macOS: コマンドパレットで「Shell Command: Install ‘code’ command in PATH」を実行

“Git not found”

Gitがインストールされていない、またはパスが通っていません。

対処法

1. Gitをインストール
2. git.path設定でGitの実行ファイルを明示的に指定

1
2
3

{
  "git.path": "C:\\Program Files\\Git\\bin\\git.exe"
}

独立した環境でのテスト

問題の切り分けのため、完全に独立した環境でVSCodeを起動できます。

別のユーザーデータディレクトリを指定

1
2
3
4
5

# 独立したテスト環境で起動
code --user-data-dir /tmp/vscode-test --extensions-dir /tmp/vscode-test-extensions

# Windows
code --user-data-dir C:\Temp\vscode-test --extensions-dir C:\Temp\vscode-test-extensions

この方法により、既存の設定や拡張機能に影響を与えずにテストできます。

Portable Modeの活用

USBドライブなどに完全に独立したVSCode環境を構築できます。

1. VSCodeのZIP版をダウンロード
2. 展開したフォルダ内にdataフォルダを作成
3. 設定と拡張機能がすべてdataフォルダ内に保存される

VSCode Insidersでの検証

安定版で問題が発生する場合、VSCode Insiders（プレビュー版）で検証することで、次期バージョンで修正されているかどうかを確認できます。

1
2
3
4
5

# VSCode Insidersで起動
code-insiders

# 拡張機能を無効にしてInsidersを起動
code-insiders --disable-extensions

Insidersは安定版と共存してインストールできます。

まとめ

VSCode トラブルシューティングの体系的なアプローチをまとめます。

問題が発生した際は、このフローに従って段階的に原因を切り分けることで、効率的に解決できます。

参考リンク

• VS Code Troubleshooting（公式ドキュメント）
• Extension Marketplace（公式ドキュメント）
• Command Line Interface（公式ドキュメント）
• Resolving extension issues with bisect（公式ブログ）
• User and Workspace Settings（公式ドキュメント）
• Uninstall Visual Studio Code（公式ドキュメント）
• VS Code GitHub Issues