Error handling: throw, reject, and never swallow

An error is an object, not a string

When something fails in Node, the useful artifact is an Error object, and almost every bug in error handling comes from treating it like a string. An Error has a message (the human line), a name ("Error", "TypeError", …), and a stack — a captured trace of where it was created, which is the single most valuable field for debugging. Node adds one more that web code lacks: system and library errors carry a stable code string like ENOENT, ECONNREFUSED, or ERR_INVALID_ARG_TYPE. You branch on code, never on message — messages are prose and change between versions; codes are API.

import { readFile } from "node:fs/promises";

try {
  await readFile("/etc/missing.conf");
} catch (err) {
  console.log(err instanceof Error); // true
  console.log(err.code);             // "ENOENT"  ← branch on this
  console.log(err.message);          // "ENOENT: no such file..."  ← log, don't parse
}

The moment you do "failed: " + err or JSON.stringify(err), you lose it: concatenation calls toString() and yields "Error: message" with no stack, and JSON.stringify returns {} because message and stack are non-enumerable. Log the object itself (logger.error({ err }), or console.error(err)) so the stack survives. This is exactly the bug in the hook: the Error was real and complete, and the + operator threw away everything except a useless prefix.

throw vs reject vs error-first callbacks

Node has three ways failure travels, and they are not interchangeable — each is bound to a call style, and mixing them is a top source of swallowed errors.

The trap is that try/catch only catches a synchronous throw in the same tick. A throw inside an asynchronous callback escapes the surrounding try entirely — by the time it runs, the try block has already returned. Likewise, calling an async function without await (or .catch) means its rejection is never observed by your try. The rule: inside async code, await everything you depend on so a rejection becomes a catchable throw; in error-first callbacks, handle err on the first line and return so you don’t fall through into the success path with data undefined.

// throw escapes — the callback runs after the try has exited
try {
  setTimeout(() => { throw new Error("boom"); }, 10); // becomes uncaughtException
} catch (e) { /* never runs */ }

// promise rejection is awaited into a catchable throw
try {
  await fetchUser(id); // rejects → caught here
} catch (e) { /* runs */ }

// error-first: check err first, then return
db.query(sql, (err, rows) => {
  if (err) return cb(err);   // stop here on failure
  cb(null, transform(rows));
});

cause and custom error classes

Catching an error to add context is good; replacing it with a vaguer one is how you lose the stack. Since Node 16.9 the standard fix is the cause option: throw a new, higher-level error while chaining the original underneath, so the trace stays intact.

class ConfigError extends Error {
  constructor(message, options) {
    super(message, options);   // forwards { cause }
    this.name = "ConfigError"; // so logs and instanceof read correctly
  }
}

try {
  await readFile(path);
} catch (err) {
  // wrap with context, keep the original ENOENT and its stack as .cause
  throw new ConfigError(`cannot load config at ${path}`, { cause: err });
}

Two senior habits live here. First, set this.name in a custom class — without it the class name is lost in serialized logs and err.name reads "Error". Second, prefer a small set of typed errors (ValidationError, NotFoundError, ConfigError) that callers can branch on with instanceof or a code property, rather than parsing messages. A modern logger or util.inspect prints the full cause chain automatically, so wrapping costs nothing and buys you the full path from symptom to root.

The process-level safety net: uncaughtException and unhandledRejection

Some errors escape every local handler — a throw in a stray callback, a promise nobody awaited. Node surfaces these on the process object, and how you treat them separates a robust service from a zombie one.

An unhandled promise rejection — a rejected promise with no .catch or await anywhere — fires process.on("unhandledRejection"), and since Node 15 the default action is to print the error and terminate the process (exit code 1). This is the right default: a rejection you forgot to handle is a bug, and continuing in an unknown state hides it. Do not “fix” it by registering a handler that just logs and swallows — that re-creates the silent-failure problem at global scope.

An uncaught synchronous exception fires process.on("uncaughtException"). The critical, counter-intuitive rule from the Node docs: after an uncaughtException the process is in an undefined state and you must not resume normal operation. A handler is for last-rites only — flush logs, fire a metric, maybe close connections — and then process.exit(1). Let a supervisor (systemd, Kubernetes, PM2) restart a clean process. The pattern below is the production shape: a thin top-level net that records and exits, paired with disciplined local handling everywhere else.

process.on("unhandledRejection", (reason) => {
  console.error("unhandledRejection:", reason); // an Error or any value
  process.exit(1);
});
process.on("uncaughtException", (err) => {
  console.error("uncaughtException:", err);
  // state is unsafe — record, then die. Do NOT keep serving.
  process.exit(1);
});