VSCodeでデバッグできない原因と対処法

VSCodeでデバッグできない場合、VSCode本体だけに原因があるとは限りません。
実際には、実行環境、デバッグ用拡張機能、launch.json、ブレークポイント、ビルド設定、ソースマップ、ポートなど、さまざまな要素が関係しています。

そのため、やみくもに設定を変更するのではなく、原因を順番に切り分けることが重要です。

まずはプログラムが通常実行できるか確認し、その後にVSCodeのデバッグ設定を確認すると、問題を効率的に特定できます。

この記事では、VSCodeでデバッグできない代表的な原因と対処法を詳しく解説します。

まずプログラムを通常実行できるか確認する

デバッグを始める前に通常実行を試す

VSCodeでデバッグできない場合、最初に確認したいのが「プログラムそのものが正常に実行できるか」という点です。

デバッグ機能に問題があるように見えても、実際にはPythonやNode.jsなどの実行環境に問題があるケースがあります。

例えばPythonの場合は、VSCodeの統合ターミナルから次のように実行します。

python main.py

環境によっては、次のコマンドを使用します。

python3 main.py

Node.jsの場合は次のように実行できます。

node app.js

通常実行の時点でエラーが発生する場合は、まずプログラム自体や実行環境の問題を解決する必要があります。

ランタイムやコンパイラが使えるか確認する

使用する言語に必要なランタイムやコンパイラがインストールされているか確認しましょう。

例えば、次のようなコマンドで確認できます。

python --version

node --version

java -version

gcc --version

コマンドが見つからない場合は、ランタイムやコンパイラがインストールされていないか、PATHが正しく設定されていない可能性があります。

ただし、特にPythonでは、PATHに登録されていなくてもVSCodeの拡張機能からインタープリターを選択できる場合があります。

そのため、PATHだけでなく、VSCode側で正しい実行環境が選択されているかも確認することが重要です。

デバッグ用の拡張機能を確認する

言語によってはデバッグ用拡張機能が必要

VSCodeは、すべての言語を標準状態でデバッグできるわけではありません。

JavaScriptやNode.jsについてはJavaScriptデバッガーがVSCodeに組み込まれています。

一方、Python、C/C++、Java、Goなどでは、それぞれ対応する拡張機能を利用するのが一般的です。

代表的には次のようなものがあります。

• Python：MicrosoftのPython拡張機能とPython Debugger
• C/C++：MicrosoftのC/C++拡張機能
• Java：Java関連の拡張機能
• Go：Go拡張機能
• C#：C#関連の拡張機能

必要な拡張機能がインストールされていない場合、デバッグ構成を作成できなかったり、F5キーを押しても正常にデバッグできなかったりすることがあります。

拡張機能が無効になっていないか確認する

拡張機能をインストールしていても、無効化されている場合があります。

VSCodeの左側にある「拡張機能」を開き、対象の拡張機能が有効になっているか確認しましょう。

また、VSCodeでは拡張機能をワークスペース単位で無効にできるため、特定のプロジェクトだけで動作しない場合は、ワークスペース側の設定も確認します。

正しい方法でデバッグを開始しているか確認する

通常実行とデバッグ実行は異なる

VSCodeでは、単純にプログラムを実行することと、デバッガーを利用して実行することは異なります。

ブレークポイントを使用したい場合は、デバッグセッションとしてプログラムを起動する必要があります。

一般的には、左側の「実行とデバッグ」を開き、デバッグ構成を選択して実行します。

F5キーを使用してデバッグを開始することもできます。

単純な「実行」だけを行っている場合、ブレークポイントが機能しないことがあるため注意しましょう。

デバッグ構成が正しく設定されているか確認する

launch.jsonが必須とは限らない

VSCodeでは、必ずしもlaunch.jsonを作成しなければデバッグできないわけではありません。

PythonやNode.jsなどでは、簡単なプログラムであればlaunch.jsonを明示的に作成せずにデバッグできる場合があります。

ただし、実行ファイル、コマンドライン引数、環境変数、作業ディレクトリ、Attach先などを細かく設定したい場合は、launch.jsonを使用します。

通常、launch.jsonは次の場所に保存されます。

.vscode/launch.json

launch.jsonを作成する

VSCodeの「実行とデバッグ」から、デバッグ構成の追加やlaunch.jsonの作成ができます。

例えば、Node.jsでは次のような設定を利用できます。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/app.js",
      "cwd": "${workspaceFolder}"
    }
  ]
}

launch.jsonに問題がある場合は、設定を一度作り直して、古い設定と比較する方法も有効です。

launch.jsonのprogramを確認する

デバッグ対象のファイルが正しいか確認する

programには、デバッグ対象となるプログラムを指定します。

例えば次の設定では、プロジェクト直下のapp.jsを実行します。

"program": "${workspaceFolder}/app.js"

実際のファイルが、

src/app.js

にある場合は、次のように修正する必要があります。

"program": "${workspaceFolder}/src/app.js"

programのパスが間違っていると、デバッグが始まらなかったり、別のプログラムが起動したりする原因になります。

ワークスペースの開き方を確認する

プロジェクトフォルダーを開いているか確認する

VSCodeでは、単一ファイルだけを開く方法と、フォルダー全体をワークスペースとして開く方法があります。

launch.jsonで次のような変数を利用している場合は注意が必要です。

"${workspaceFolder}"

${workspaceFolder}は、VSCodeで開いているワークスペースフォルダーを表します。

例えば次の構成であれば、my-projectフォルダーをVSCodeで開くのが基本です。

my-project/
├─ .vscode/
│  └─ launch.json
├─ src/
│  └─ app.js
└─ package.json

単一ファイルだけを開いていると、workspaceFolderを前提とした設定が正しく動作しないことがあります。

cwdの設定を確認する

作業ディレクトリが違うとファイルを読み込めないことがある

cwdは「Current Working Directory」の略で、プログラムを実行するときの作業ディレクトリを指定します。

例えば次のように設定します。

"cwd": "${workspaceFolder}"

プログラム内で相対パスを利用している場合、cwdが違うと必要なファイルを読み込めないことがあります。

例えば、次のコードがあるとします。

fs.readFileSync("./config.json");

この場合、config.jsonの検索位置は作業ディレクトリによって変わります。

「ターミナルから実行すると動くのに、デバッグするとファイルが見つからない」という場合は、cwdを確認しましょう。

ブレークポイントで停止しない原因を確認する

そのコードが実際に実行されているか確認する

ブレークポイントを設定しても、その行が実際に実行されなければ停止しません。

例えば次の関数があっても、

function test() {
  console.log("test");
}

test()が一度も呼び出されていなければ、内部に設定したブレークポイントは動作しません。

一時的にログを追加して、対象コードが実際に通過しているか確認する方法もあります。

console.log("ここを通過");

ブレークポイントが未検証になっていないか確認する

ブレークポイントが通常とは異なる薄い表示になっていたり、未検証の状態になっていたりする場合があります。

その場合、デバッガーがその位置を有効なブレークポイントとして認識できていない可能性があります。

主な原因としては、次のようなものがあります。

• ソースコードと実際に実行しているコードが一致していない
• ビルド結果が古い
• ソースマップが正しく生成されていない
• 別のファイルを実行している
• 実行可能な処理がない行にブレークポイントを設定している

ブレークポイントが反応しない場合は、単純に再設定するだけでなく、デバッグ対象のコードが正しいか確認しましょう。

古いビルド結果をデバッグしていないか確認する

ソースコードと実行ファイルがずれている場合がある

TypeScript、Java、C/C++などでは、編集しているソースコードと実際に実行しているファイルが異なる場合があります。

例えばTypeScriptでは、

src/app.ts

を編集していても、実際にNode.jsが実行しているのは、

dist/app.js

というケースがあります。

ソースコードを編集した後にビルドしていなければ、VSCodeが古いJavaScriptをデバッグしてしまう可能性があります。

ブレークポイントが止まらない場合や、変更内容が反映されない場合は、一度ビルドし直してから再度デバッグしましょう。

preLaunchTaskが失敗していないか確認する

デバッグ前のビルド処理を確認する

launch.jsonでは、デバッグ開始前に特定のタスクを実行できます。

例えば次のような設定です。

"preLaunchTask": "build"

この場合、処理の流れは次のようになります。

デバッグ開始
↓
preLaunchTask実行
↓
ビルド
↓
デバッグ開始

preLaunchTaskで指定したビルドが失敗すると、デバッグが開始されない場合があります。

また、launch.jsonのpreLaunchTaskとtasks.jsonのlabelが一致しているかも確認しましょう。

Pythonの実行環境を確認する

正しいPythonインタープリターを選択する

Pythonでは、VSCodeが使用しているPythonと、ターミナルで普段使用しているPythonが違うことがあります。

例えば、次のような複数の環境が存在する場合です。

システムPython
.venv
conda環境

VSCodeではコマンドパレットから「Python: Select Interpreter」を実行し、使用するPython環境を選択できます。

仮想環境にだけライブラリをインストールしている場合、別のPythonを選択していると次のようなエラーが発生することがあります。

ModuleNotFoundError

WindowsでPythonの場所を確認する場合は、PowerShellなら次のようなコマンドを使用できます。

where.exe python

または、

Get-Command python

macOSやLinuxでは次のように確認できます。

which python

または、

which python3

PythonのJust My Code設定を確認する

ライブラリ内部へステップインできない場合がある

Pythonでは、ユーザーが作成したコードを中心にデバッグするための「Just My Code」という考え方があります。

この設定が有効になっていると、外部ライブラリ内部へステップインできない場合があります。

自分のコードではデバッグできるのに、ライブラリ内部へ入れない場合は、デバッガーの設定を確認しましょう。

これは「デバッグ機能が壊れている」のではなく、デバッグ対象を限定する設定によって発生している可能性があります。

C/C++のデバッグ環境を確認する

コンパイラとデバッガーは役割が異なる

C/C++では、コンパイラとデバッガーを区別して考える必要があります。

例えば、GCCやClang、MSVCなどは主にコンパイルを担当します。

一方、GDBやLLDBなどは主にデバッグを担当します。

VSCodeのC/C++拡張機能をインストールしただけで、すべてのコンパイラやデバッガーが自動的に用意されるわけではありません。

C/C++でデバッグできない場合は、次の項目を確認しましょう。

• コンパイラがインストールされているか
• デバッガーがインストールされているか
• 実行ファイルが生成されているか
• programが正しい実行ファイルを指しているか
• preLaunchTaskでビルドできているか

Node.jsのAttach設定を確認する

デバッグポートが一致しているか確認する

Node.jsでは、すでに起動しているプロセスへVSCodeから接続する「Attach」を利用できます。

この場合、Node.js側のデバッグポートとVSCode側の設定が一致している必要があります。

例えばNode.jsをデバッグ可能な状態で起動し、VSCodeのlaunch.jsonから同じポートへ接続します。

ポート番号が一致していなければ、VSCodeから接続できません。

Node.jsでは、launch.jsonを使用する方法以外にも、Auto AttachやJavaScript Debug Terminalなどの方法があります。

利用しているデバッグ方法に合った設定になっているか確認しましょう。

ポート競合を確認する

別のプロセスが同じポートを使っていないか確認する

WebアプリケーションやAttach形式のデバッグでは、ポート競合が原因になることがあります。

例えば次のようなエラーです。

Port 3000 is already in use

Windowsでは次のように確認できます。

netstat -ano | findstr :3000

macOSやLinuxでは次のようなコマンドを利用できます。

lsof -i :3000

不要なプロセスを終了するか、アプリケーション側のポート番号を変更して対応します。

ブラウザーデバッグの設定を確認する

URLや開発サーバーを確認する

Webフロントエンドをデバッグする場合は、ブラウザー側の設定にも注意が必要です。

例えばMicrosoft Edgeを起動する場合は、次のような設定を使用できます。

{
  "type": "msedge",
  "request": "launch",
  "name": "Launch App",
  "url": "http://localhost:3000"
}

この場合、http://localhost:3000で開発サーバーが正常に起動している必要があります。

ブラウザーデバッグができない場合は、次の点を確認しましょう。

• URLが正しいか
• ポート番号が正しいか
• 開発サーバーが起動しているか
• ブラウザーのデバッグ構成が正しいか
• launchとattachを取り違えていないか

VSCodeではlaunch.jsonを利用する方法だけでなく、「Debug: Open Link」からURLを開いてデバッグする方法もあります。

参考サイト

【VSCode】JavaScript（ブラウザ）デバッグでブレークポイントで停止しない時の対処

ソースマップを確認する

TypeScriptなどでは元ソースとの対応付けが必要

TypeScriptや、Webpack、Viteなどを利用するプロジェクトでは、実際に実行されるJavaScriptと編集しているソースコードが異なる場合があります。

例えば、次のような流れです。

TypeScript
↓
JavaScriptへ変換
↓
Node.jsやブラウザーで実行

このとき、元のTypeScriptと生成されたJavaScriptを対応付けるためにソースマップが使用されます。

ソースマップに問題があると、次のような症状が発生する場合があります。

• ブレークポイントが有効にならない
• 意図しない行で停止する
• TypeScript側で停止しない
• 元のソースファイルを正しく特定できない

TypeScriptのデバッグがうまくいかない場合は、tsconfig.jsonやビルドツール側のソースマップ設定を確認しましょう。

環境変数を確認する

通常実行とデバッグ実行で環境変数が違う場合がある

アプリケーションによっては、環境変数を利用して動作します。

例えば次のようなものです。

NODE_ENV
DATABASE_URL
API_KEY

通常実行では環境変数が設定されているのに、VSCodeのデバッグ実行では設定されていないと、プログラムが正常に動作しない場合があります。

必要に応じてlaunch.jsonで環境変数を指定できます。

"env": {
  "NODE_ENV": "development"
}

「ターミナルでは動くがデバッグでは動かない」という場合は、環境変数の違いも確認しましょう。

ファイルパスを確認する

OSによるパスの違いに注意する

Windows、macOS、Linuxではファイルパスの扱いが異なります。

launch.jsonでは、できるだけVSCodeの変数を利用すると環境差を減らしやすくなります。

例えば次のように指定できます。

"${workspaceFolder}/src/app.js"

Windowsでバックスラッシュを直接記述する場合は、JSON上でエスケープが必要になることがあります。

そのため、固定パスを大量に記述するよりも、${workspaceFolder}などを活用する方が管理しやすくなります。

DockerやWSLの実行環境を確認する

VSCodeとプログラムの実行場所が違う場合がある

DockerやWSLを利用している場合は、VSCodeを操作している環境とプログラムが動作している環境が異なることがあります。

例えば、次のような構成です。

Windows上のVSCode
↓
Dockerコンテナ内でNode.jsを実行

この場合、ローカル用のデバッグ設定では接続できないことがあります。

次の点を確認しましょう。

• プログラムがどの環境で動いているか
• デバッガーがどの環境で動いているか
• デバッグポートが公開されているか
• ホスト側とコンテナ側のパスが対応しているか
• Attach先のホスト名とポートが正しいか
• 必要な拡張機能がリモート環境で利用できるか

ローカルではデバッグできるのにDockerやWSLではできない場合は、実行環境の違いを重点的に確認すると原因を見つけやすくなります。

複数のデバッグ構成を確認する

間違ったデバッグ構成を選択していないか確認する

launch.jsonには複数のデバッグ構成を登録できます。

例えば次のような構成です。

{
  "configurations": [
    {
      "name": "Frontend",
      "type": "msedge",
      "request": "launch"
    },
    {
      "name": "Backend",
      "type": "node",
      "request": "launch"
    }
  ]
}

バックエンドをデバッグしたいのにFrontendを選択していれば、Node.js側のブレークポイントは機能しません。

F5キーを押す前に、「実行とデバッグ」で正しい構成が選択されているか確認しましょう。

マルチルートワークスペースにも注意する

VSCodeでは複数のフォルダーを1つのワークスペースとして開くことができます。

この場合、各フォルダーごとに異なるlaunch.jsonが存在することがあります。

意図しないフォルダーのデバッグ構成を選択すると、別のプログラムが起動したり、設定した環境変数が反映されなかったりすることがあります。

拡張機能の競合を確認する

類似した拡張機能を複数入れている場合に注意する

同じ言語やデバッグ機能を扱う拡張機能を複数インストールしていると、競合する場合があります。

問題が疑われる場合は、最近追加した拡張機能や不要な拡張機能を一時的に無効化して確認します。

次の流れで切り分けると分かりやすくなります。

1. 最近追加した拡張機能を無効にする
2. VSCodeを再読み込みする
3. デバッグを再実行する
4. 問題が解消するか確認する

大量の拡張機能をインストールしている場合は、競合の可能性も考慮しましょう。

VSCodeや拡張機能を再起動する

一時的な不具合を切り分ける

設定に問題がなくても、一時的な状態によってデバッグできないことがあります。

その場合は、VSCodeを再読み込みすることで改善することがあります。

それでも改善しない場合は、次の対処を試しましょう。

• VSCodeを再起動する
• 拡張機能を更新する
• VSCodeを更新する
• 拡張機能を無効化して再度有効にする
• PCを再起動する

設定を大きく変更する前に、一度再起動を試しておくとよいでしょう。

エラーの確認場所を確認する

デバッグ コンソールを確認する

VSCodeでデバッグが正常に開始できない場合は、「デバッグ コンソール」を確認します。

デバッガーから出力されたエラーや情報が表示されるため、原因特定の重要な手掛かりになります。

ターミナルを確認する

プログラムそのもののエラーは、統合ターミナルに表示されることがあります。

例えば次のようなエラーです。

Module not found

Permission denied

Address already in use

File not found

エラーメッセージをそのまま検索したり、内容を確認したりすると原因を特定しやすくなります。

出力パネルを確認する

拡張機能やデバッガーによっては、「出力」パネルにログが表示されます。

「出力」を開き、プルダウンから対象となる拡張機能やデバッグ機能を選択して確認しましょう。

launch.jsonで確認したい主な設定

type

typeでは、使用するデバッガーの種類を指定します。

例えばNode.jsでは次のように設定します。

"type": "node"

使用している言語やデバッガーに対応している必要があります。

request

requestでは、デバッグ開始方法を指定します。

主に次の2種類があります。

"request": "launch"

launchは、VSCodeからプログラムを起動してデバッグする方式です。

一方、

"request": "attach"

attachは、すでに実行中のプロセスへVSCodeから接続する方式です。

program

programでは、デバッグ対象となるプログラムを指定します。

"program": "${workspaceFolder}/src/app.js"

パスが正しいか確認しましょう。

cwd

cwdでは、作業ディレクトリを指定します。

"cwd": "${workspaceFolder}"

相対パスでファイルを扱うアプリケーションでは特に重要です。

args

コマンドライン引数を渡したい場合はargsを使用します。

"args": [
  "--mode",
  "development"
]

env

環境変数を指定したい場合はenvを利用できます。

"env": {
  "NODE_ENV": "development"
}

通常実行とデバッグ実行で動作が異なる場合は、これらの設定を確認しましょう。

実行できるのにブレークポイントで止まらない場合の確認手順

1．デバッグ実行しているか確認する

通常実行ではなく、F5キーや「実行とデバッグ」からデバッグセッションを開始します。

2．対象コードが実行されているか確認する

ログなどを追加し、その行をプログラムが本当に通過しているか確認します。

3．ブレークポイントの状態を確認する

未検証の状態になっていないか確認します。

4．最新コードをビルドする

TypeScript、C/C++、Javaなどでは、最新のコードがビルドされているか確認します。

5．正しいプログラムを起動しているか確認する

launch.jsonのprogramや、選択しているデバッグ構成を確認します。

6．ソースマップを確認する

TypeScriptやバンドラーを使用している場合は、ソースマップの設定を確認します。

デバッグ自体が開始しない場合の確認手順

1．通常実行できるか確認する

まずターミナルから直接プログラムを実行します。

2．ランタイムを確認する

PythonやNode.jsなどが正常に利用できるか確認します。

3．デバッグ用拡張機能を確認する

必要な拡張機能がインストールされ、有効になっているか確認します。

4．デバッグ構成を確認する

launch.jsonを使用している場合は、特に次の項目を確認します。

• type
• request
• program
• cwd

5．preLaunchTaskを確認する

デバッグ前のビルド処理が失敗していないか確認します。

6．デバッグ コンソールを確認する

エラーメッセージが表示されていないか確認しましょう。

VSCodeでデバッグできないときの症状別早見表

F5を押してもデバッグが始まらない

主な原因として、次のものが考えられます。

• 必要な拡張機能がない
• 実行環境が正しくない
• デバッグ構成が間違っている
• preLaunchTaskが失敗している

ブレークポイントで止まらない

主な原因として、次のものが考えられます。

• 対象コードが実行されていない
• 古いビルド結果を実行している
• ソースマップに問題がある
• 別のファイルを実行している
• ブレークポイントが未検証になっている

通常実行はできるがデバッグできない

主な原因として、次のものが考えられます。

• launch.jsonの設定
• cwdの違い
• 環境変数の違い
• 使用しているPython環境などの違い
• デバッグ対象の構成が違う

Attachできない

主な原因として、次のものが考えられます。

• ポート番号が違う
• 対象プロセスが起動していない
• requestが正しくない
• Dockerなどでポートが公開されていない

VSCodeでデバッグできないときのおすすめの切り分け順序

1．通常実行できるか確認する

最初にターミナルからプログラムを実行します。

通常実行できなければ、まず実行環境やプログラムの問題を解決します。

2．実行環境を確認する

Python、Node.js、Java、C/C++などの実行環境を確認します。

3．必要な拡張機能を確認する

対応するデバッグ用拡張機能が有効になっているか確認します。

4．簡単なプログラムでデバッグを試す

簡単なコードでデバッグできるか確認すると、VSCode全体の問題なのか、現在のプロジェクト固有の問題なのかを切り分けやすくなります。

例えばNode.jsなら、次のような単純なコードで試せます。

const name = "VSCode";
console.log(name);

5．デバッグ構成を確認する

launch.jsonを使用している場合は、type、request、program、cwd、preLaunchTask、envなどを確認します。

6．ブレークポイントを確認する

正しいファイルの実行可能な行に設定されているか確認します。

7．ログを確認する

デバッグ コンソール、ターミナル、出力パネルを確認します。

8．VSCodeを再起動する

一時的な問題を切り分けます。

9．拡張機能を切り分ける

最近追加した拡張機能などを一時的に無効化して確認します。

まとめ

VSCodeでデバッグできない場合は、VSCode本体だけでなく、プログラムの実行環境やデバッグ設定も含めて確認することが重要です。

特に最初に確認したいのは、プログラムがターミナルから通常実行できるかどうかです。

通常実行できない場合は、デバッグ設定よりも先に、ランタイム、コンパイラ、依存ライブラリ、PATHなどを確認します。

通常実行できるのにデバッグだけできない場合は、次にデバッグ用拡張機能やデバッグ構成を確認します。

特に重要なのは、次のポイントです。

• 正しいランタイムやインタープリターを使用しているか
• 必要なデバッグ用拡張機能が有効か
• 正しいデバッグ構成を選択しているか
• programのパスが正しいか
• cwdが正しいか
• preLaunchTaskが成功しているか
• ブレークポイントを設定したコードが実際に実行されているか
• 最新のコードがビルドされているか
• ソースマップが正しく設定されているか
• 環境変数やポート番号が正しいか
• DockerやWSLなどの実行環境が一致しているか

原因が分からない場合でも、「通常実行→実行環境→拡張機能→デバッグ構成→ブレークポイント→ログ」という順番で確認すると、問題を効率的に切り分けられます。

VSCodeでデバッグできないときは、設定を一度に変更するのではなく、1つずつ原因を確認していくことが解決への近道です。

以上、VSCodeでデバッグできない原因と対処法についてでした。

最後までお読みいただき、ありがとうございました。