You set a breakpoint in your TypeScript or bundled ESM code inside VS Code, launch the debugger, and watch the red dot turn hollow gray. The tooltip says the breakpoint is unbound, or worse, it pauses twenty lines away inside compiled code full of mangled variable names like _t2 and r.default.

text
Could not read source map for file:///workspace/dist/index.js: ENOENT: no such file or directory, root/workspace/dist/index.js.map
Breakpoint set but not yet bound.
Paused on line 482 of dist/bundle.js (source-mapped file: undefined)

The debugger cannot bridge your original files and the executed code when source map path resolution breaks. When this happens, advanced features like conditional breakpoints and logpoints fail silently or evaluate against nonexistent runtime variables.

Why path mapping desynchronizes

Node.js executes compiled JavaScript from a build directory like dist or .build. Your editor looks at files in src. When a tool like tsc, esbuild, or vite generates a source map, it writes two properties inside the .map file: sources (an array of relative paths back to the source files) and optionally sourceRoot.

If the compiler emits:

json
{
  "version": 3,
  "file": "server.js",
  "sources": ["../src/server.ts"],
  "sourcesContent": []
}

VS Code resolves ../src/server.ts relative to the directory containing server.js.map. If your launch configuration does not specify outFiles, the debugger searches your entire workspace for matching map files. On medium or large projects, this search times out, binds to stale maps in cache folders, or matches the wrong files in a monorepo.

To inspect how the debugger sees your files, open the Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on macOS) and run:

text
Debug: Diagnose Breakpoint Problems

Or write this command into the Debug Console while paused:

text
.scripts

This dumps every loaded script, every registered source map, and whether the path resolved correctly.

The bulletproof launch.json for Node.js

To stop unbound breakpoints in compiled or bundled Node services, configure outFiles, sourceMaps, and resolveSourceMapLocations explicitly in .vscode/launch.json.

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Current Service",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "npm: build",
      "outFiles": [
        "${workspaceFolder}/dist/**/*.js",
        "!**/node_modules/**"
      ],
      "sourceMaps": true,
      "smartStep": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!**/node_modules/**"
      ],
      "skipFiles": [
        "<node_internals>/**",
        "${workspaceFolder}/node_modules/**"
      ],
      "console": "integratedTerminal"
    }
  ]
}

If you attach to an already running process instead of launching it directly, use an attach configuration:

json
{
  "type": "node",
  "request": "attach",
  "name": "Attach to Backend",
  "port": 9229,
  "restart": true,
  "sourceMaps": true,
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "${workspaceFolder}",
  "outFiles": [
    "${workspaceFolder}/dist/**/*.js"
  ],
  "skipFiles": [
    "<node_internals>/**"
  ]
}

When building your TypeScript, your tsconfig.json must generate both maps and declaration maps without stripping source roots:

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "inlineSources": true,
    "declaration": true,
    "declarationMap": true
  },
  "include": ["src/**/*"]
}

Setting "inlineSources": true embeds the original source code directly into the .map file. It eliminates path resolution errors because the debugger never needs to read the disk to match original source lines.

Full-stack browser and SSR debugging

If you debug code that runs in both the browser and Node (such as Next.js, Remix, or a Vite app), the browser adapter runs into URL mapping issues. The browser serves files under paths like http://localhost:3000/src/main.ts or webpack://_N_E/src/main.ts.

Add sourceMapPathOverrides to map incoming browser URLs back to your local filesystem.

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Chrome against localhost",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:5173",
      "webRoot": "${workspaceFolder}",
      "sourceMaps": true,
      "sourceMapPathOverrides": {
        "webpack:///src/*": "${webRoot}/src/*",
        "webpack:///*": "*",
        "/src/*": "${webRoot}/src/*",
        "vite:///src/*": "${webRoot}/src/*"
      }
    }
  ]
}

Run .scripts in the Debug Console while Chrome is connected to see the exact URL schemes the dev server serves. If you see webpack://[name]/src/app.ts, you add that specific prefix to the left side of sourceMapPathOverrides.

Conditional breakpoints without runtime crashes

Once the debugger binds to your TypeScript sources, you can set conditional breakpoints. Right-click the gutter next to a line number and select Add Conditional Breakpoint….

There are two primary evaluation traps: scope availability and side effects.

Consider this endpoint handling an e-commerce order:

typescript
export async function processOrder(orderId: string, items: OrderItem[]) {
  const account = await fetchAccountByOrder(orderId);
  const total = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
  
  // Line to inspect
  const paymentResult = await chargeGateway(account.stripeId, total);
  return paymentResult;
}

If you set a conditional breakpoint on the const paymentResult line with the condition:

javascript
account.balance < total && items.length > 5

The debugger evaluates that expression inside the runtime environment at that specific execution point. But remember: runtime variables might be minified or renamed if your source maps do not include a complete names mapping table.

If your build tool renames account to e and total to t, your condition throws a ReferenceError during evaluation:

text
Evaluation failed: ReferenceError: account is not defined

To prevent this:

  1. Turn off variable mangling during local development builds. In esbuild, set minify: false or keep minifyIdentifiers: false. In Terser or Webpack, use optimization: { minimize: false }.
  2. Keep conditions side-effect-free. Never execute mutating functions inside the condition. Expressions like items.pop().price > 100 alter state during evaluation and will cause hard-to-track bugs.
  3. Handle potential null pointers. Use optional chaining inside your breakpoint conditions:
javascript
account?.balance !== undefined && account.balance < total

You can also use hit counts instead of plain boolean conditions. If an endpoint fails on a specific iteration of a loop or after handling several requests, select Hit Count from the condition dropdown and input:

text
> 50

The debugger pauses only when that line executes for the fifty-first time.

Fast diagnostics with logpoints

Console logs require a rebuild or trigger a hot module reload, which can wipe your current application state. Logpoints allow you to log messages to the Debug Console without editing code or restarting processes.

Right-click the gutter and select Add Logpoint….

Logpoints accept plain text, but interpolate expressions enclosed in curly braces {}:

text
Processing order {orderId} for customer {account?.name ?? "Anonymous"}, total: {total}

Logpoints do not pause execution. They resolve the expressions against the local scope and output the result to the VS Code Debug Console.

text
Processing order ord_88192 for customer Jane Doe, total: 149.50

You can call built-in runtime methods inside these braces:

text
Payload size: {Buffer.byteLength(JSON.stringify(items))} bytes at {new Date().toISOString()}

Gotcha 1: The esbuild and tsx inline source map mismatch

Modern Node projects often use tsx or ts-node to run TypeScript files directly without an explicit build step. These tools compile on the fly and append inline source maps as base64 data URIs to the executed files.

If you attach VS Code to a process started via tsx watch src/index.ts, breakpoints often refuse to bind because VS Code inspects the disk while tsx runs from memory.

To fix this with tsx:

Run the process with Node’s native inspector flag exposed:

bash
node --loader tsx --inspect=9229 src/index.ts

For Node 20.6.0 and newer, use the native compile cache and module flags instead of external loaders:

bash
node --import=tsx --inspect=0.0.0.0:9229 src/index.ts

In .vscode/launch.json, point to the process by name or attach to the port directly. Do not pass program when attaching to tsx, rely on port:

json
{
  "type": "node",
  "request": "attach",
  "name": "Attach to TSX",
  "port": 9229,
  "skipFiles": ["<node_internals>/**"]
}

If the breakpoint remains unbound, run this in your terminal to verify that the map is being exposed on the target process:

bash
curl -s http://127.0.0.1:9229/json | grep -i devtoolsFrontendUrl

If this returns an empty response, the process is not listening on that debug interface.

In pnpm or yarn monorepos, your source files might reside in packages/core/src, while the executing code runs from apps/api/node_modules/@workspace/core/dist.

When you place a breakpoint inside packages/core/src/index.ts, VS Code checks its local path. The executing Node process reports that it is running code from apps/api/node_modules/.... Because the paths do not match, the breakpoint stays unbound.

Resolve this by setting preserveSymlinks: true in your build config or Node process, and configure sourceMapPathOverrides or resolveSourceMapLocations in your VS Code launch task to follow real workspace paths:

json
{
  "resolveSourceMapLocations": [
    "${workspaceFolder}/**",
    "!**/node_modules/**",
    "${workspaceFolder}/packages/**"
  ]
}

In your root package.json launch script, pass:

bash
node --preserve-symlinks --inspect dist/index.js

This prevents Node from resolving realpaths to symlinked packages, allowing the debugger to match your original files in the workspace editor tree.

Verification

To verify that your configuration works:

  1. Place a logpoint on a frequently executed line:
    text
    DEBUG HIT: {account.id}
    
  2. Start debugging (F5).
  3. Check the Loaded Scripts section in the Run & Debug side panel.
  4. Expand your project folder. The original .ts or .jsx files must appear in the tree, not just the .js files from dist.
  5. Trigger the code path. The message should display in the Debug Console without execution pausing.
  6. Convert the logpoint to a conditional breakpoint:
    javascript
    account.id === "target_id"
    
  7. Trigger the code path again with matching and non-matching data. The debugger must halt only when the expression evaluates to true.

More in JavaScript