Node.js Async Control-Flow, Errors & Context Propagation

Node.js Async Control-Flow — Cancellation, Structured Errors & Context

Overview

This reference is the layer above basic promises. Once you can await, three problems remain: how do you cancel an in-flight operation, how do you carry structured error information (not just a string), and how do you keep per-request context (a request id, a trace span, a tenant) alive as control hops across await points, timers, and callbacks. Cancellation, structured errors, and async context are what this file covers.

It defers three adjacent topics: the intro layer (what a promise is, async/await, .then/.catch) → javascript-nodejs; the libuv event-loop phase model, microtask-vs-macrotask ordering, and process.nextTick starvation → nodejs-concurrency-internals; and diagnostics_channel / channel.bindStore() / TracingChannel for APM-style instrumentation → nodejs-diagnostics-profiling (this file uses AsyncLocalStorage for your own request context).

The mental model: a unit of async work should be cancellable (carries an AbortSignal), should fail with a typed, chainable error (carries code + cause), and should run inside a context (AsyncLocalStorage) any nested async call can read without threading an argument through every function.

Core concepts

1. Cancellation — AbortController / AbortSignal

AbortController is the standard cancellation primitive (Web-platform, available globally in Node — no import). A controller owns one signal; calling controller.abort(reason) flips signal.aborted to true, records signal.reason, and fires the 'abort' event.

const ac = new AbortController();
ac.signal.addEventListener('abort', () => console.log('cancelled:', ac.signal.reason),
                           { once: true });            // { once: true } avoids a leak
setTimeout(() => ac.abort(new Error('user navigated away')), 5_000);
await fetch(url, { signal: ac.signal });               // rejects with the reason on abort

• The signal is the cancellation token. Pass signal into the options of any abort-aware API: fetch(url, { signal }), node:timers/promises (setTimeout(ms, value, { signal })), fs.readFile(path, { signal }), events.once(emitter, name, { signal }), and stream/pipeline operations. The API rejects (or rejects the awaited promise) with an AbortError (err.code === 'ABORT_ERR') — or with your custom reason if you passed one to abort().
• signal.reason is whatever you passed to abort(reason); if you passed nothing it defaults to a DOMException named AbortError. signal.throwIfAborted() throws that reason immediately — call it at the top of and between steps in a long async function so a late-arriving cancellation short-circuits.
• 'abort' event: register a listener (with { once: true }) to run teardown that the awaited API can’t do for you (close a file you opened, roll back).

2. Composing signals — AbortSignal.timeout() and AbortSignal.any()

The two static factories are what make cancellation composable:

• AbortSignal.timeout(ms) returns a signal that auto-aborts after ms (with a TimeoutError reason). It does not keep the event loop alive — it won’t, by itself, prevent the process from exiting.
• AbortSignal.any([...signals]) returns a signal that aborts as soon as any input aborts, adopting that signal’s reason. This is how you OR together a request-deadline and a user-cancel:

import { setTimeout as delay } from 'node:timers/promises';
const userCancel = new AbortController();
const signal = AbortSignal.any([userCancel.signal, AbortSignal.timeout(10_000)]);
await fetch(url, { signal });   // aborts on whichever fires first; reason tells you which

AbortSignal.abort(reason) returns an already-aborted signal — handy for tests or for passing “already cancelled” into a function uniformly.

3. Structured errors — Error.cause, AggregateError, custom classes

A thrown string loses information. Node + modern JS give you three structuring tools:

• Error.cause — the second-argument options bag: new Error('msg', { cause }). It chains a low-level failure to a higher-level one without flattening the message, and util.inspect/stack printing walks the chain. Re-throw with context, keep the original:

  try { await db.query(sql); }
  catch (cause) { throw new Error('failed to load user profile', { cause }); }

• AggregateError — holds multiple errors in err.errors (an array). This is exactly what Promise.any rejects with when every input rejects, and the right type to throw when you’ve collected several failures (see Promise.allSettled below).

• Custom error classes — subclass Error, set a stable code, and (optionally) carry cause. Always set name and code:

  class ConfigError extends Error {
    constructor(message, opts) { super(message, opts); this.name = 'ConfigError'; this.code = 'E_CONFIG'; }
  }

4. The error.code convention — match on code, never message

Node attaches a stable string code to its errors (ERR_INVALID_ARG_TYPE, ABORT_ERR, ENOENT, ECONNREFUSED, …). The docs are explicit: error.code changes only across major Node versions, while error.message may change in any version. Branch on code, not on the message — message matching is a latent bug that breaks on upgrade and across locales.

try { await fs.readFile(p); }
catch (err) {
  if (err.code === 'ENOENT') return null;   // stable
  if (err.code === 'ABORT_ERR') return;     // cancelled, not an error
  throw err;                                // unknown — re-throw, don't swallow
}

5. Process-level failure — rejections, exceptions, and exit semantics

Two process events are the safety net of last resort:

• 'unhandledRejection' (reason, promise) — a Promise rejected with no handler attached within a turn of the loop. 'rejectionHandled' (promise) fires if a handler is attached later — track a Map keyed by the promise to reconcile the two (add on unhandledRejection, delete on rejectionHandled) and report only the survivors.
• 'uncaughtException' (err, origin) — an exception bubbled to the loop with no try/catch. 'uncaughtExceptionMonitor' observes it without changing the crash-or-not behavior (use it to log to an APM, then let the normal handling run).

Why uncaughtException must generally be fatal. The docs state it plainly: an uncaught exception means the app is in an undefined state; 'uncaughtException' is not an On Error Resume Next. The correct use is synchronous cleanup of resources (flush a log, release file descriptors) and then exit — let an external supervisor restart the process. Resuming after it is unsafe.

Exit semantics. Prefer setting process.exitCode = n and letting the loop drain naturally over process.exit(n), which terminates synchronously and can truncate buffered stdout/stderr. The 'exit' event handler may run synchronous code only — queued async work is abandoned the instant it returns.

--unhandled-rejections=<mode> controls rejection handling: throw (the default since Node 15 — emit the event, else raise as an uncaught exception), strict (always raise as uncaught), warn (always warn, never throw), warn-with-error-code (warn and set a nonzero exit code), and none (silence entirely).

6. Promise concurrency — all vs allSettled vs any vs race

The four combinators differ on fail-fast vs collect-all and on fulfillment vs first-settled:

The teaching point: all is fail-fast (one rejection abandons the others’ results), allSettled is collect-all (you get every outcome, success and failure, and inspect status). Use all when any failure should abort the batch; use allSettled for “do all of these, then tell me what worked.” race settles on the first outcome of either kind; any ignores rejections until a fulfilment (or gives you an AggregateError).

Concurrency limiting. Promise.all(items.map(fn)) fires all tasks at once — fine for 10, a thundering herd for 10,000 (socket exhaustion, rate-limit bans). Cap in-flight work with a pool (a small worker-count loop pulling from a shared iterator, or a library like p-limit). This is the practical complement to the combinators.

7. Context propagation — AsyncLocalStorage (+ async_hooks/AsyncResource)

AsyncLocalStorage (from node:async_hooks) carries a value through an async call chain without threading it as a parameter — the canonical use being a per-request id or trace context that any nested function can read:

import { AsyncLocalStorage } from 'node:async_hooks';
const als = new AsyncLocalStorage();

http.createServer((req, res) => {
  als.run({ reqId: crypto.randomUUID() }, () => handle(req, res)); // store survives awaits
});
function log(msg) { console.log(als.getStore()?.reqId, msg); }     // reads it anywhere downstream

• run(store, cb, ...args) is the API you want 95% of the time: it scopes store to cb and every async operation spawned inside it, then restores the previous store. Nested run calls shadow cleanly.
• getStore() returns the current store (or undefined outside any run).
• enterWith(store) sets the store for the rest of the current synchronous execution and onward — with no automatic exit. The docs warn this leaks easily (e.g. a second event-handler on the same emitter inherits it). Prefer run(); reach for enterWith() only with a strong reason. exit(cb) runs cb outside the store; disable() tears the instance down.
• AsyncLocalStorage.snapshot() captures the current context and returns a function that re-enters it later — useful for re-binding a callback to the context it was created in without a full AsyncResource. AsyncLocalStorage.bind(fn) wraps a function so it always runs in the captured context.
• Performance / when to use. It is the recommended, stable, optimized mechanism — far better than rolling your own with async_hooks. It is not free (context tracking has a measured cost), so use it for genuinely cross-cutting state (request id, trace, tenant), not as a general-purpose variable bag.

When the context is lost, the propagation broke at a boundary AsyncLocalStorage can’t see — a callback queued by native/3rd-party code, an object-pool worker, or a long-lived emitter. That is the job of async_hooks and AsyncResource, the low-level layer:

• async_hooks.createHook({ init, before, after, destroy }) registers lifecycle callbacks for every async resource; executionAsyncId() / triggerAsyncId() expose the current resource and the one that scheduled it. This is the machinery AsyncLocalStorage is built on.
• AsyncResource is the piece you actually use directly: wrap a callback that will be invoked later (from a connection pool, a cache, a custom emitter) so it runs in the correct context. Construct new AsyncResource('MyThing') and call resource.runInAsyncScope(cb, thisArg, ...args), or wrap once with the static AsyncResource.bind(fn). This is how you re-attach context across a pool boundary.
• Caveat: async_hooks is Stability 1 (experimental) and low-level; the docs explicitly discourage using the hook API directly and steer you to AsyncLocalStorage for context tracking. Use AsyncResource.bind for the pool-callback case; avoid building context systems on raw createHook.

Key APIs

Practical patterns

• util.promisify(fn) converts an error-first callback function (…, (err, value) => …) into a promise-returning one; util.callbackify(fn) does the reverse for an async function. If a function ships a better promise form, it advertises it on the util.promisify.custom symbol and promisify returns that instead of wrapping the callback. (Most core modules already expose node:fs/promises etc. — promisify is for third-party or legacy callback APIs.)
• Thread one signal through a whole operation. Accept { signal } in your own async functions, call signal.throwIfAborted() between steps, and forward the same signal to every downstream call (fetch, timers, fs) so one abort() unwinds the entire tree.
• Time-box with AbortSignal.any([userSignal, AbortSignal.timeout(ms)]) instead of racing a manual setTimeout reject — composition is cleaner and you keep the abort reason.
• Reconcile rejections with the Map pattern: add on 'unhandledRejection', delete on 'rejectionHandled', report the residue on shutdown.
• Re-bind pool callbacks with AsyncResource.bind(cb) (or AsyncLocalStorage.bind) at enqueue time so the dequeued callback runs in the right request context.

Anti-patterns

• Serialized awaits in a loop — for (const x of xs) await f(x) when the calls are independent. That’s sequential latency; use await Promise.all(xs.map(f)) (with a concurrency cap for large xs).
• Unbounded Promise.all over a huge array — fires every task at once and exhausts sockets / trips rate limits. Cap in-flight work.
• Treating 'uncaughtException' as resume-and-continue — the process is in an undefined state; do sync cleanup, then exit and let a supervisor restart.
• process.exit() to “finish” — truncates buffered output and abandons pending work; set process.exitCode and let the loop drain.
• Matching on err.message — breaks across versions and locales; match on err.code.
• Swallowing errors (catch {}), or catching without re-throwing the unknown ones — you lose the failure and the cause chain. Narrow on code, re-throw the rest.
• AsyncLocalStorage.enterWith() in shared/event-handler code — leaks the store into unrelated later callbacks; use run().
• Building a context system on raw async_hooks.createHook — it’s experimental and error-prone (a throw in a hook is fatal); use AsyncLocalStorage / AsyncResource.

Troubleshooting

• fetch/op doesn’t actually stop on abort → you logged 'abort' but didn’t pass signal into the call’s options, or you created a new controller per retry; pass the same signal down and check signal.aborted.
• Caught error but instanceof MyError is false → you compared types across a module boundary or the error was re-wrapped; branch on err.code (and inspect err.cause) instead.
• Promise.any “fails” unexpectedly → it rejects with an AggregateError only when all inputs reject; read err.errors. If you wanted first-settled, use race.
• Process crashes despite an uncaughtExceptionMonitor listener → monitor does not suppress the crash; install an 'uncaughtException' handler (that then exits) if you must intercept, but don’t resume.
• als.getStore() is undefined downstream → context was lost at a native/pool/emitter boundary; wrap the callback with AsyncResource.bind / AsyncLocalStorage.bind, or promisify a callback API so the store propagates. Don’t paper over it with enterWith().
• Unhandled rejection silently ignored → check --unhandled-rejections; if set to warn/none it won’t crash. Default (throw) surfaces it.

References

• Node.js — Globals: AbortController / AbortSignal (abort, reason, throwIfAborted, timeout(), any()): https://nodejs.org/api/globals.html
• Node.js — Errors: Error.cause, error.code convention (match code not message), AggregateError, ABORT_ERR/system codes: https://nodejs.org/api/errors.html
• Node.js — Process: uncaughtException / unhandledRejection / rejectionHandled / uncaughtExceptionMonitor, process.exitCode vs process.exit(), 'exit': https://nodejs.org/api/process.html
• Node.js — CLI: --unhandled-rejections=<throw|strict|warn|warn-with-error-code|none>: https://nodejs.org/api/cli.html
• Node.js — util.promisify / util.callbackify / util.promisify.custom: https://nodejs.org/api/util.html
• Node.js — Async context tracking: AsyncLocalStorage (run/getStore/enterWith/exit/snapshot/bind) and AsyncResource: https://nodejs.org/api/async_context.html
• Node.js — async_hooks (createHook init/before/after/destroy, executionAsyncId/triggerAsyncId; experimental, prefer AsyncLocalStorage): https://nodejs.org/api/async_hooks.html
• MDN — Promise.all / Promise.allSettled / Promise.any (AggregateError) / Promise.race: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise