Debugging

Node Inspector handles step-debugging in Chrome DevTools or VS Code; structured Pino logs handle the rest.

4 min read Level 2/5 #fastify#debugging#devtools

What you'll learn

Run with node --inspect-brk
Attach VS Code to a running process
Enable TypeScript source maps in builds

You won’t reach for a step-debugger every day — Pino logs and tests are usually enough — but when you need one, Node Inspector plus DevTools is excellent.

Start With Inspector Open

# pause before user code runs
node --inspect-brk dist/index.js

# or attach without pausing
node --inspect dist/index.js

# TypeScript via tsx
npx tsx --inspect src/index.ts

Visit chrome://inspect and click inspect under the target. Set breakpoints, step through, watch values — works exactly like the browser.

VS Code Attach

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Fastify",
      "port": 9229,
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

Source Maps

For step-debugging compiled TypeScript, enable source maps in tsconfig.json:

{
  "compilerOptions": {
    "sourceMap": true,
    "inlineSources": true
  }
}

Otherwise breakpoints land on the generated JS, which is hard to read.

Production Diagnostics

For live processes you can’t attach to: enable OpenTelemetry for distributed traces, Sentry for errors, and pino’s req.log.error(err, 'context') for ad-hoc debugging. Combined with /metrics, you rarely need a debugger in production.

Going Further →