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.
textCould 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:
textDebug: 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:
typescriptexport 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:
javascriptaccount.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:
textEvaluation failed: ReferenceError: account is not defined
To prevent this:
- Turn off variable mangling during local development builds. In
esbuild, setminify: falseor keepminifyIdentifiers: false. In Terser or Webpack, useoptimization: { minimize: false }. - Keep conditions side-effect-free. Never execute mutating functions inside the condition. Expressions like
items.pop().price > 100alter state during evaluation and will cause hard-to-track bugs. - Handle potential null pointers. Use optional chaining inside your breakpoint conditions:
javascriptaccount?.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 {}:
textProcessing 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.
textProcessing order ord_88192 for customer Jane Doe, total: 149.50
You can call built-in runtime methods inside these braces:
textPayload 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:
bashnode --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:
bashnode --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:
bashcurl -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.
Gotcha 2: Monorepo symlinks and mismatched paths
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:
bashnode --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:
- Place a logpoint on a frequently executed line:text
DEBUG HIT: {account.id} - Start debugging (
F5). - Check the Loaded Scripts section in the Run & Debug side panel.
- Expand your project folder. The original
.tsor.jsxfiles must appear in the tree, not just the.jsfiles fromdist. - Trigger the code path. The message should display in the Debug Console without execution pausing.
- Convert the logpoint to a conditional breakpoint:javascript
account.id === "target_id" - Trigger the code path again with matching and non-matching data. The debugger must halt only when the expression evaluates to
true.