Errors and Debugging

Throw, catch, and diagnose failures with structured errors and built-in debug tools. Results appear in the same fence: same-line // comments when short, multiline // blocks below the sample when not.

Error cause Chain

Attach an underlying error with { cause } to preserve context.

const root = new Error("db down");
const err = new Error("query failed", { cause: root });
(err.cause as Error).message  // "db down"
err.message                   // "query failed"

Custom Error Class

Subclass Error for typed handling and stable name / code fields.

class AppError extends Error {
  constructor(readonly code: string, message: string) {
    super(message);
    this.name = "AppError";
  }
}
const e = new AppError("E_AUTH", "nope");
e.code   // "E_AUTH"
e.name   // "AppError"

assert strict

Fail fast in scripts and tests with node:assert/strict.

import assert from "node:assert/strict";
assert.equal(1 + 1, 2);
assert.ok(true);
// assert.equal(1, 2) throws AssertionError

NODE_DEBUG

Enable core debug categories with the NODE_DEBUG environment variable.

// NODE_DEBUG=http,net node app.js
process.env.NODE_DEBUG ?? ""  // "" unless set

stack Trace Limit

Increase stack trace depth when diagnosing deep call chains.

Error.stackTraceLimit = 50;
Error.stackTraceLimit  // 50

util inspect Depth

Pretty-print objects with controlled depth and colors.

import { inspect } from "node:util";
const s = inspect({ a: { b: 1 } }, { depth: 2, colors: false });
s.includes("b: 1")  // true

debuglog util

Create a debug logger gated by NODE_DEBUG namespaces.

import { debuglog } from "node:util";
const debug = debuglog("myapp");
typeof debug  // "function"
// prints only when NODE_DEBUG=myapp

AggregateError

Wrap multiple failures from Promise.any or batch jobs.

const err = new AggregateError(
  [new Error("a"), new Error("b")],
  "all failed",
);
err.errors.length  // 2
err.message        // "all failed"

try finally Close

Always close resources in finally even when throwing.

const steps: string[] = [];
try {
  steps.push("body");
} finally {
  steps.push("finally");
}
steps
// ["body", "finally"]

isError Guard

Narrow unknown catch values before reading message/stack.

function messageOf(e: unknown) {
  return e instanceof Error ? e.message : String(e);
}
messageOf(new Error("x"))  // "x"
messageOf("y")             // "y"

Operational vs Programmer

Retry operational errors (timeouts); crash or alert on programmer bugs (TypeError).

const e = Object.assign(new Error("timeout"), { code: "ETIMEDOUT" });
(e as any).code === "ETIMEDOUT"  // true
// if operational -> retry; if TypeError -> throw

unhandledRejection Hook

Centralize unhandled rejection logging in long-running servers.

// process.on("unhandledRejection", (r) => console.error("unhandled", r));
typeof process.on  // "function"

trace SIGUSR

Prefer inspector for stacks; signal-based debugging is platform-specific.

// node --inspect=9229 app.js  then chrome://inspect
process.execArgv  // may include inspect flags when set

assert rejects

Assert that an async function rejects in tests.

import assert from "node:assert/strict";
await assert.rejects(async () => {
  throw new Error("fail");
}, /fail/);
// passes when rejection matches

DomException Abort

AbortError names appear from AbortSignal - detect and ignore cancellation.

const ac = new AbortController();
ac.abort();
const e = new DOMException("Aborted", "AbortError");
e.name  // "AbortError"
// if ((e as Error).name === "AbortError") return;

Async Patterns - async error propagation
HTTP and Fetch - map errors to status codes
Performance Diagnostics - profiling beyond logs

Node.js API Documentation - Complete reference for core modules and APIs.
Node.js Best Practices (GitHub) - Curated production best practices.
Stack Overflow – Node.js Tag - Q&A for real-world problems.
Node.js Cookbook, 5th Edition - Practical server-side recipes.
Node.js Design Patterns, 4th Edition - Production-grade application patterns.

Stack versions: Node.js 24.18.0 (LTS line 24) · TypeScript 5.6+ · npm 10+

Reviewed by Chris St. John·Last updated Jul 18, 2026

Was this article helpful?

Reference Code Reference Errors Debugging Diagnostics

Errors and Debugging

Error cause Chain

Attach an underlying error with { cause } to preserve context.

const root = new Error("db down");
const err = new Error("query failed", { cause: root });
(err.cause as Error).message  // "db down"
err.message                   // "query failed"

Custom Error Class

Subclass Error for typed handling and stable name / code fields.

class AppError extends Error {
  constructor(readonly code: string, message: string) {
    super(message);
    this.name = "AppError";
  }
}
const e = new AppError("E_AUTH", "nope");
e.code   // "E_AUTH"
e.name   // "AppError"

assert strict

Fail fast in scripts and tests with node:assert/strict.

import assert from "node:assert/strict";
assert.equal(1 + 1, 2);
assert.ok(true);
// assert.equal(1, 2) throws AssertionError

NODE_DEBUG

Enable core debug categories with the NODE_DEBUG environment variable.

// NODE_DEBUG=http,net node app.js
process.env.NODE_DEBUG ?? ""  // "" unless set

stack Trace Limit

Increase stack trace depth when diagnosing deep call chains.

Error.stackTraceLimit = 50;
Error.stackTraceLimit  // 50

util inspect Depth

Pretty-print objects with controlled depth and colors.

import { inspect } from "node:util";
const s = inspect({ a: { b: 1 } }, { depth: 2, colors: false });
s.includes("b: 1")  // true

debuglog util

Create a debug logger gated by NODE_DEBUG namespaces.

import { debuglog } from "node:util";
const debug = debuglog("myapp");
typeof debug  // "function"
// prints only when NODE_DEBUG=myapp

AggregateError

Wrap multiple failures from Promise.any or batch jobs.

const err = new AggregateError(
  [new Error("a"), new Error("b")],
  "all failed",
);
err.errors.length  // 2
err.message        // "all failed"

try finally Close

Always close resources in finally even when throwing.

const steps: string[] = [];
try {
  steps.push("body");
} finally {
  steps.push("finally");
}
steps
// ["body", "finally"]

isError Guard

Narrow unknown catch values before reading message/stack.

function messageOf(e: unknown) {
  return e instanceof Error ? e.message : String(e);
}
messageOf(new Error("x"))  // "x"
messageOf("y")             // "y"

Operational vs Programmer

Retry operational errors (timeouts); crash or alert on programmer bugs (TypeError).

const e = Object.assign(new Error("timeout"), { code: "ETIMEDOUT" });
(e as any).code === "ETIMEDOUT"  // true
// if operational -> retry; if TypeError -> throw

unhandledRejection Hook

Centralize unhandled rejection logging in long-running servers.

// process.on("unhandledRejection", (r) => console.error("unhandled", r));
typeof process.on  // "function"

trace SIGUSR

Prefer inspector for stacks; signal-based debugging is platform-specific.

// node --inspect=9229 app.js  then chrome://inspect
process.execArgv  // may include inspect flags when set

assert rejects

Assert that an async function rejects in tests.

import assert from "node:assert/strict";
await assert.rejects(async () => {
  throw new Error("fail");
}, /fail/);
// passes when rejection matches

DomException Abort

AbortError names appear from AbortSignal - detect and ignore cancellation.

const ac = new AbortController();
ac.abort();
const e = new DOMException("Aborted", "AbortError");
e.name  // "AbortError"
// if ((e as Error).name === "AbortError") return;

Async Patterns - async error propagation
HTTP and Fetch - map errors to status codes
Performance Diagnostics - profiling beyond logs

Node.js API Documentation - Complete reference for core modules and APIs.
Node.js Best Practices (GitHub) - Curated production best practices.
Stack Overflow – Node.js Tag - Q&A for real-world problems.
Node.js Cookbook, 5th Edition - Practical server-side recipes.
Node.js Design Patterns, 4th Edition - Production-grade application patterns.

Stack versions: Node.js 24.18.0 (LTS line 24) · TypeScript 5.6+ · npm 10+

Reviewed by Chris St. John·Last updated Jul 18, 2026

Was this article helpful?

Errors and Debugging

Search Documentation

Errors and Debugging