Callbacks & the Error-First Convention

"Callbacks suffer from inversion of control in that they implicitly give control over to another party." — Kyle Simpson, You Don't Know JS: Async & Performance

Part I described the machine. This Part is about the code you write on top of it, and it starts where Node started: with a function you hand to somebody else, to be called when they are ready.

That arrangement is older than Node and older than JavaScript, and on its own it is unremarkable. What makes it worth a chapter is the thing Simpson names above — you are not calling a function, you are surrendering control of your program's continuation to someone else. Everything that follows in this Part is a response to the problems that surrender creates. Promises are a response. async/await is a response to promises. Understanding why they exist requires understanding what they were fixing, and a great deal of the Node ecosystem still runs on the thing being fixed.

The convention that emerged is error-first: the callback's first parameter is an error, or null when there is none. It is a convention rather than a language feature, which is the entire source of both its reach and its fragility. Nothing enforces it. Nothing checks that a callback runs once, or runs asynchronously, or runs at all. The compiler has no opinion. Each of those unenforced guarantees is a bug class, and this chapter is largely a tour of them — because they are precisely the guarantees promises later made structural.

The convention, and the cost of not following it

Error-first is simple enough to state in a sentence: the first argument is an error or null, the rest are results. Its weakness is equally simple — nothing makes you look at the first argument.

The careless handler does not crash. It receives undefined where it expected an object, reads a property off it, gets undefined again, and carries on — writing that undefined into a database or a response body. The error was delivered correctly and simply not examined, which is the defining weakness of the convention: an unchecked error is indistinguishable from no error until much later and somewhere else.

Three rules make error-first tolerable in practice.

The error check is the first statement in the callback. Not somewhere in the middle. If it is not the first line, a reviewer cannot tell at a glance whether it exists.

return when you handle the error. if (err) callback(err); without a return continues into the success path as well, calling the callback twice with contradictory arguments. This is such a common bug that return callback(err) is idiomatic even where the return value is meaningless.

Errors must be Error objects. callback("something failed") loses the stack trace, and if (err) is then testing a string — which fails silently for the empty string. Reject anything that calls back with a string, a number, or true.

Zalgo: the function that is sometimes synchronous

The single most damaging thing a callback API can do is be inconsistent about when it calls you back.

Read the two outputs against each other. On the cache miss the callback runs after load has finished, so handle is assigned. On the cache hit the callback runs during load, before the next line executes, so handle is still null. The calling code is identical and correct in both cases; the API changed the rules underneath it.

Why this is so hard to debug in practice:

It passes every test. Tests usually start with an empty cache, so every call takes the async path.

It fails intermittently in production, on the second request for the same resource, under load — the conditions least amenable to a debugger.

The stack trace points at the caller, which is correct code. Nothing in the trace indicates that the timing of the callback is the variable.

The fix is one line, in the API rather than the caller:

// Not runnable here — process.nextTick is Node-only. `queueMicrotask` or
// `setImmediate` work equally well; the point is to defer by at least a turn.
if (cache.has(id)) return process.nextTick(() => callback(null, cache.get(id)));

Always asynchronous, even when the answer is already in hand. The cost is one turn of the event loop; the benefit is that the caller's code has one behaviour instead of two.

The pyramid, and why it is not merely ugly

"Callback hell" is usually presented as an aesthetic complaint about indentation. The indentation is the symptom; the real cost is that error handling is duplicated at every level, and omitting one instance is silent.

Four steps require four identical error branches, and a fifth step requires a fifth. Every one is an opportunity to forget the return, to handle the error and continue anyway, or to omit the check entirely — and none of those mistakes produces a compile error or a test failure on the happy path.

The waterfall helper is thirty years old in spirit and about eight lines long, and it is what the async library packaged for the ecosystem. It gives a single error path for the whole sequence, which is exactly the property promise chains provide natively with one .catch() at the end.

Two structural problems remain even with helpers, and they are why promises won.

A callback pyramid cannot be composed. You cannot return the sequence from a function and let the caller decide what to do with it — the only way out is another callback, so the callback-ness propagates up through every layer of your codebase.

A callback has no value. There is nothing to store, pass, or return that represents "the eventual result". A promise is a value representing a future result, and that single change is what makes composition possible.

The contract callbacks cannot enforce

A promise has three guarantees built into it: it settles once, it settles asynchronously, and it settles either fulfilled or rejected. A callback has none of them, and each absence is a bug you will meet.

The second violation is worth studying, because it is genuinely confusing when met in the wild. A TypeError in your success handler — reading a property of undefined, say — gets caught by the library, reported as though the operation failed, and delivered back to the very handler that produced it. The logs then show a database call failing with Cannot read properties of undefined, and an hour disappears into the database.

The safe shape for a library is to invoke the callback outside the try, or to rethrow asynchronously so the error surfaces as an uncaught exception rather than being laundered into a result. And on your side: do not throw from a callback. There is nowhere for the exception to go that is useful.

Which leaves the third guarantee: a callback might simply never run. A library with an early return that forgets to call back leaves your program waiting forever, with no error, no timeout, and no stack. There is no defence at the call site beyond wrapping every call in a timeout, which nobody does. A promise cannot do this to you silently, because an unresolved promise awaited in an async function is at least visible to a heap dump — and unhandled rejection tracking catches the error case outright.

Escaping: turning a callback into a promise

Converting is mechanical, which is why it can be done generically. Building promisify is the clearest possible demonstration of what a promise adds.

Look at what changed. The error is now caught by try/catch rather than checked by if, so forgetting to handle it is loud rather than silent — an unhandled rejection is reported, whereas an unchecked err argument is not. The results compose: Promise.all runs two operations concurrently in one line, which with callbacks requires a counter, a results array, and a once guard to avoid calling back twice.

Three practical notes.

Node ships this. util.promisify handles the same conversion, respects a util.promisify.custom symbol for APIs whose callback shape is unusual, and is preferable to hand-rolling.

Many APIs now offer promises directly. fs/promises, timers/promises, and dns/promises exist precisely so conversion is unnecessary. Check before wrapping.

Multi-value callbacks are the awkward case. A callback invoked as cb(null, a, b) has no natural promise equivalent, since a promise resolves to one value. The wrapper above returns an array; util.promisify returns only the first value unless told otherwise. This is a rare shape, and it is worth knowing why it is rare — the promise model quietly pushed APIs toward returning one thing.

Common Mistakes

1. Not checking err at all. The error is delivered and ignored, and undefined flows onward as though it were data.

2. Handling the error without return. if (err) callback(err); falls through into the success path and calls back twice.

3. Calling back with a string instead of an Error. No stack trace, and if (err) is now testing truthiness of a string.

4. Releasing Zalgo. An API that answers synchronously on a cache hit and asynchronously otherwise makes the caller's code order-dependent on a cache.

5. Throwing from inside a callback. There is nowhere useful for it to go, and a defensive library may launder it into a fake operation error.

6. Assuming the callback will definitely run. An early return that forgets to call back hangs the caller forever, silently.

7. Letting callback style propagate upward. Convert at the boundary; otherwise every caller above it must also be callback-based.

8. Hand-rolling parallel callback control flow. A counter plus a results array plus a completion guard is three chances to be wrong; Promise.all is one line.

9. Wrapping an API that already has a promise version. Check fs/promises and friends before reaching for promisify.

10. Trusting a third-party callback to be called once. Wrap it in once() at any boundary where a double call would corrupt state.

Interview Corner

Hands-on

Summary

• A callback is an inversion of control — you hand another party the continuation of your program, and everything difficult about callbacks follows from that.
• Error-first is a convention, not a guarantee. Nothing forces you to inspect the first argument, and an unchecked error is silent.
• Always return after handling an error, or execution falls through and the callback runs twice.
• Errors must be Error objects — strings lose the stack and break truthiness checks.
• Never call back synchronously on some paths and asynchronously on others. That is Zalgo, and it makes the caller's behaviour depend on a cache.
• Promises rule Zalgo out at the specification level: .then is always scheduled as a microtask, even on a settled promise.
• The pyramid's real cost is duplicated error handling, one branch per level, each a chance to omit a check silently.
• A callback has no value, so it cannot be returned, stored or composed — which is why callback style propagates upward through a codebase.
• Callbacks guarantee nothing about arity or timing: they may run twice, or never. once() guards the first; nothing guards the second.
• Convert at the boundary. Wrap the callback API once, and keep everything above it async/await.

This chapter described the problem. The next describes the answer the language settled on: a promise is a value representing a future result, with a small state machine behind it — pending, fulfilled, rejected — that can only move once and can only move in one direction. That single constraint eliminates most of this chapter's bug classes by construction rather than by discipline, and understanding the state machine is what makes the difference between using promises and reasoning about them.