In a Node.js service, what separates an operational error from a programmer error, and which one calls for a retry, a client-error response, or a crash?
answer
- expected failure versus bug
- correct code, unreliable world
- transient versus permanent
- same input, same failure
- context decides the class
basics
~20 sIn Node.js, an operational error is a failure correct code must expect, such as ENOENT or ECONNRESET; a programmer error is a bug, such as ERR_INVALID_ARG_TYPE. Retry transient operational errors, report permanent ones, and never retry bugs.
solid answer
~50 sAn operational error is the world failing while the code is correct: a file removed before the sync reached it (`ENOENT`), a peer resetting the connection (`ECONNRESET`), a timeout, invalid user input. A programmer error is a bug: an object passed where Node wants a path (`TypeError [ERR_INVALID_ARG_TYPE]`), a property read on `undefined`, a failed `assert`, a callback called twice. Handle operational errors: retry transient ones with bounded backoff when the work is idempotent, and report permanent ones, which in an HTTP service usually means a 4xx for bad input. Never retry a programmer error, because the same code fails the same way; fail loudly, and if it escaped to the process level, let the process exit and be restarted. Context decides the response: `ENOENT` on a user's file is reported, on the service's own config at startup it should stop the service starting.
code
javascript · 8 linesconst TRANSIENT = new Set(['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE', 'ENOTFOUND']);
const PERMANENT = new Set(['ENOENT', 'EACCES', 'EPERM', 'EISDIR', 'ENOTDIR']);
export function triage(err) {
if (TRANSIENT.has(err?.code)) return 'retry'; // bounded backoff, idempotent work only
if (PERMANENT.has(err?.code)) return 'report'; // skip the file and record why
return 'bug'; // ERR_* argument errors and unknown failures: fail loudly, never retry
}go deeper
Recall the two definitions with an example each: ENOENT or ECONNRESET for operational, a wrong argument type or a read of undefined for a programmer error.
Explain the triage: bounded retry for transient operational errors, reporting for permanent ones, no retry for bugs, and classifying by code rather than message.
Show the context cases: ENOENT at startup versus on user data, missing validation turning bad input into a TypeError, and why retries need idempotency.
Own the team's taxonomy: which codes are retryable, where the single retry layer lives, and when a service refuses to start instead of limping on.
## Two kinds of failure The split between **operational** and **programmer** errors is a convention from the Node.js community rather than a Node API: Node's errors documentation lists categories such as standard JavaScript errors, system errors and `AssertionError`s, and leaves the triage to you. The convention survives because it answers the practical question every catch site faces: **can this be handled, or is the code wrong?** - An **operational error** is a failure a **correct program must expect**, because the world it runs in is unreliable: a file deleted before the sync reached it, a peer that resets the connection, a timeout, a full disk, a port already in use, invalid input from a user. - A **programmer error** is a **bug**: the code did something it should never do. Passing an object where Node wants a path, reading a property of `undefined`, a failed `assert`, a callback called twice. The distinction matters because the remedies are opposite. An operational error has a **handling strategy**: retry it, report it, fall back. A programmer error has only a **fix**, and the fix is a code change. ## How to tell them apart in Node | Signal | Usually | Why | |---|---|---| | system `code` such as `ECONNRESET`, `ETIMEDOUT`, `ECONNREFUSED` | operational, transient | the network or peer failed; the same call can succeed later | | `ENOENT`, `EACCES`, `EEXIST` on data the user chose | operational, permanent | retrying cannot create the file or grant the permission | | `TypeError` with an `ERR_INVALID_ARG_TYPE` or `ERR_INVALID_ARG_VALUE` code | programmer | Node validated arguments and the caller passed the wrong thing | | `TypeError: Cannot read properties of undefined` | programmer | the code assumed a value that was not there | | `AssertionError` from `node:assert` | programmer | Node's docs describe it as a logic violation that should never occur | ## The triage 1. **Classify by `code` first**, then by class. The code says what failed; the class alone is rarely enough. 2. **Transient operational errors get a bounded retry.** Use exponential backoff with a cap and a limit, and only for **idempotent** work; a retried non-idempotent write can apply twice. 3. **Permanent operational errors get reported.** Skip the file and record why, surface a clear message, or, in an HTTP service, answer with a client-error status for bad input. Retrying wastes capacity and delays the signal. 4. **Programmer errors are never retried.** Fail that operation loudly with its stack, alert on it, and fix the code. If one escaped all handlers to the process level, Node's process documentation says it is not safe to resume after `'uncaughtException'`; let the process exit and be restarted, as the crash-policy material describes. ## Context changes the answer The same code can land on either side: - **`ENOENT` on a user's file** is operational: report it. **`ENOENT` on the service's own config file at startup** means the deployment is broken: refuse to start. - **`ECONNREFUSED` from a dependency** during normal work is transient. At startup, before the service has ever connected, it may be a wrong host name, which no retry fixes. - **A `TypeError` caused by a request body missing a field** is a bad input reaching code that never validated it. The input is the client's fault, the missing validation is yours: validate at the boundary so the failure becomes an explicit operational error with its own code. - **`EMFILE`** is operational in form but often has a programmer cause, leaked handles or unbounded parallelism. ## Where the decision lives Retries belong in **one** layer. If the storage client retries three times, the sync job retries each file three times and the scheduler reruns failed jobs three times, a single unreachable peer turns into 27 attempts and an alert that arrives far too late. Pick the layer that knows whether the work is idempotent, usually the one closest to the operation, and let the layers above see the final, classified failure. ## What goes wrong - **Retrying everything.** A retry loop around a bug multiplies load and hides the stack under timeouts. - **Swallowing everything.** `catch (err) {}` turns both kinds into silent data loss. - **Crashing on everything.** Exiting on a single `ECONNRESET` turns a routine network blip into an outage. - **Classifying by message text** instead of `code`, which breaks when the text changes.
- Why is retrying a programmer error worse than useless?A bug is deterministic: the same input runs the same broken code and fails the same way. Retries multiply load, delay the alert by the whole backoff schedule and bury the original stack under timeouts. If the operation had side effects before it failed, each retry can repeat them.
- A request handler throws a TypeError because a client sent JSON without an expected field. Is that operational or a programmer error?Both halves are present: the bad input is operational and deserves a client-error answer, but reaching a `TypeError` means validation is missing, which is a bug. Validate input at the boundary so the failure becomes an explicit operational error with its own code instead of a crash deep in the code.
- Must a Node.js service exit on every programmer error?Not on one that is caught: a bug thrown inside one request and caught by its handler can fail that request with its stack logged and an alert raised. What must not happen is resuming after an error that escaped to `'uncaughtException'`; Node's process documentation says that is not safe, so the process should exit and be restarted.
- Retry every failure a few times; something will eventually work.
- A TypeError is always the client's fault, so answer 4xx and move on.
- Any ECONNRESET means the process is corrupted and must exit.
- Classify errors by searching the message for words like 'timeout'.
- ENOENT always means skip the file and carry on, whatever file it was.