Launch vs Attach Debugging in VS Code: What Is the Difference?

Launch vs attach is the first choice you make when setting up a debug configuration. Launch starts your program and connects the debugger. Attach connects to something already running. Understanding both modes lets you pick the right tool for local development, remote debugging, and production troubleshooting.

What launch mode does

When to use launch

Use launch for everyday local development. You have a file or project open in VS Code and want to start debugging with a single keystroke.

Press F5. VS Code runs your program, attaches the debugger, and pauses at your breakpoints. When you stop the session, VS Code stops the program. When you restart, VS Code starts a fresh instance.

A launch configuration in your settings file looks like this:

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch Server",
  "program": "${workspaceFolder}/server.js"
}

The request field set to launch tells VS Code to start the program. You define the entry point with the program field and can add arguments and environment variables, or a pre-launch build task.

Launch is the default mode when you press F5 for the first time in a new workspace. VS Code tries to launch and debug the active file.

When to use attach

Use attach when the program is already running. Common scenarios:

• A server you started from a terminal outside VS Code.
• A Node.js process managed by a process manager like pm2.
• A browser you opened manually for testing.
• A remote debugging session where the code runs on another machine.

With attach, you do not restart the program. You connect to an existing process and inspect its current state. This is useful when restarting is expensive, when the startup sequence is complex, or when you want to debug a live system without disrupting it.

An attach configuration looks like this:

json

{
  "type": "node",
  "request": "attach",
  "name": "Attach to Process",
  "processId": "${command:pickProcess}"
}

The processId field uses a command variable. When you press F5, VS Code shows a list of running Node.js processes. Pick one and the debugger connects.

Set up attach for Node.js

Start your Node.js program with the inspect flag:

bash

node --inspect server.js

The program prints a debugger listening message. It runs normally until you attach from VS Code. Create the attach configuration shown above, select it in the Run and Debug dropdown, and press F5. Pick your process from the list.

To pause execution immediately on attach, use --inspect-brk instead of --inspect. The program pauses on the first line, giving you time to set breakpoints before it continues.

Set up attach for browsers

Start your browser in debug mode:

bash

chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

The remote-debugging-port flag tells the browser to listen for a debugger connection. The user-data-dir flag forces a separate browser profile so your normal browsing session is not affected.

In your settings file, create an attach configuration:

json

{
  "type": "chrome",
  "request": "attach",
  "name": "Attach to Chrome",
  "port": 9222
}

Press F5 and VS Code connects to the browser. You can set breakpoints in your JavaScript files and they trigger when the browser loads the page.

Launch and attach in the same project

You can have both modes available in the same settings file. Define two configurations and switch between them in the dropdown.

For launch, set request to "launch" with a program path. For attach, set request to "attach" and use the process picker command. Use Launch Server during active development. Use Attach to Server when you need to inspect a running instance without restarting.

For multi-service projects where you need to debug a client and server together, compound configurations let you start both from one action.

Troubleshooting

Attach shows no processes

The program must be started with the inspect flag for Node.js or remote-debugging-port for browsers. Check that the flag is present and that the port is not blocked by a firewall.

Attach connects but breakpoints do not work

The source files in VS Code must match the running code. If you compiled, minified, or transpiled the code, make sure source maps are enabled and the outFiles field points to the correct output directory.

Launch fails with "port already in use"

A previous instance of your program is still running. Stop it and try again. On macOS and Linux, use lsof -i :PORT to find the process. On Windows, use netstat -ano | findstr :PORT.