In Node.js, what does a system error such as ENOENT or ECONNRESET carry, and why should code branch on error.code rather than error.message?
answer
- from the operating system, via libuv
- string label versus free text
- a number that varies by platform
- syscall, path, address, port
- messages change in any release
basics
~20 sA Node.js system error is a plain Error with a string code such as ENOENT, a negative platform-specific errno, the failing syscall, and a path or address when relevant. Node documents code as stable; message text may change in any release.
solid answer
~40 sWhen an operation fails at the operating-system level, Node raises a system error: an ordinary `Error` instance with extra properties. `code` is the string label (`ENOENT`, `EACCES`, `ECONNRESET`, `EADDRINUSE`), `errno` is libuv's negative number, `syscall` names the failed call (`open`, `connect`, `listen`), and `path`, `dest`, `address` or `port` appear when relevant. The message is assembled from those parts, such as `ENOENT: no such file or directory, open 'a.txt'`. Branch on `code`: Node's errors documentation calls it the most stable way to identify an error, changing only between major versions, while message strings may change in any version. Avoid `errno` as well, because its numbers are platform-dependent; `util.getSystemErrorName(err.errno)` maps one back to its name.
code
javascript · 12 linesimport { readFile } from 'node:fs/promises';
import { getSystemErrorName } from 'node:util';
try {
await readFile('/data/inbox/missing.txt');
} catch (err) {
console.log(err instanceof Error); // true: system errors are plain Errors
console.log(err.code); // ENOENT
console.log(err.syscall, err.path); // open /data/inbox/missing.txt
console.log(getSystemErrorName(err.errno)); // ENOENT, whatever the platform's number
if (err.code !== 'ENOENT') throw err; // only a vanished file is expected here
}go deeper
Recall that a system error carries a string code like ENOENT or ECONNRESET, and that code is what you compare, not the message.
Explain the full set of properties, errno, syscall, path, address and port, why errno is platform-dependent, and what the common codes mean.
Show how code drives behaviour in production: which codes a worker retries, which it reports, and why syscall and path belong in every log line.
Decide how a team documents and tests the error codes its modules emit, so callers can rely on them the way they rely on Node's own.
## What a system error is Node's errors documentation sorts the errors an application meets into a few **categories**: standard JavaScript errors (`TypeError`, `RangeError` and the rest), `DOMException`s, **system errors**, `AssertionError`s from `node:assert`, and errors your own code creates. A **system error** is raised when an operation breaks an **operating-system constraint**: opening a file that does not exist, binding a port another process holds, writing to a socket the peer has closed. Node gets these from **libuv**, the C library under its I/O, and turns them into JavaScript errors. Two facts about their type surprise people: - A system error is an ordinary **`Error` instance**. `err instanceof Error` is `true`, and the instance reports `Error` as its constructor. - The docs describe a `SystemError` **shape**, but Node's public modules export no `SystemError` constructor, so you cannot write `err instanceof SystemError`. You recognise one by its properties. ## The properties it carries | Property | Meaning | Example | |---|---|---| | `code` | string label of the error | `'ENOENT'` | | `errno` | negative number from libuv, platform-dependent | `-2` | | `syscall` | the system call that failed | `'open'`, `'connect'`, `'listen'` | | `path` / `dest` | file paths, for file-system errors | `'/data/inbox/a.txt'` | | `address` / `port` | network target, for socket errors | `'127.0.0.1'`, `5432` | | `info` | extra details, when present | an object | Node builds the `message` from those parts, for example `ENOENT: no such file or directory, open 'a.txt'`. ## Why `code`, not `message` or `errno` - **`code` is the documented contract.** The errors page calls it the most stable way to identify an error: it only changes between **major** versions of Node.js. - **`message` is free text.** The same page says message strings may change in **any** version, so `err.message.includes('no such file')` can break on a patch release. - **`errno` is not portable.** The mapping between numbers and names is platform-dependent: `ECONNRESET` is `-104` on Linux and `-54` on macOS. If you only have the number, `util.getSystemErrorName(err.errno)` returns the name and `util.getSystemErrorMessage(err.errno)` the text. ## Codes a file-sync service meets The errors page lists the commonly seen codes. Here they are with the response a file-sync worker usually gives them; the response is your policy, not Node's. | `code` | What happened | Usual response | |---|---|---| | `ENOENT` | a path component does not exist | skip or report; the file may have been removed | | `EACCES` / `EPERM` | permission denied / needs privileges | do not retry; fix the configuration | | `EEXIST` | the target already exists | decide: overwrite, rename or skip | | `EISDIR` / `ENOTDIR` | a file and a directory were confused | a bug or bad input; do not retry | | `EMFILE` | the process hit its open file-descriptor limit | back off, cap concurrency, look for leaked handles | | `ECONNREFUSED` | nothing is listening at the target | retry with backoff | | `ECONNRESET` | the peer closed the connection abruptly | retry if the operation is idempotent | | `ETIMEDOUT` | the peer did not respond in time | retry with backoff | | `EPIPE` | wrote to a connection the peer had closed | reconnect, then retry | | `ENOTFOUND` | DNS lookup failed (not a POSIX code) | retry briefly, then check the host name | | `EADDRINUSE` | the port is already bound | fail startup, or retry `listen` later | ## Node's own codes share the property Errors that Node itself raises, mostly argument validation and API misuse, also carry a `code`, prefixed `ERR_`. The code appears in the stack header, as in `TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string...`. One deliberate exception is `ABORT_ERR`, which drops the prefix to stay compatible with the web platform's `AbortError`. Both families are matched the same way, by `code`. ## Practical checks 1. Read `err.code` first; fall back to `err.message` only for logging. 2. Treat a missing `code` as "not a known system or Node error" rather than guessing from the text. 3. Log `syscall` and `path` or `address` with the code: `EACCES` on `open` and `EACCES` on `listen` are different incidents. 4. Never compare `errno` against a hard-coded number in code that runs on more than one platform.
- Node's own errors also have a code, such as ERR_INVALID_ARG_TYPE. How do they differ from system errors?`ERR_*` codes come from Node itself, mostly argument validation and API misuse, and show in the stack header as `TypeError [ERR_INVALID_ARG_TYPE]: ...`. System codes such as `ENOENT` come from the operating system through libuv and arrive with `errno` and `syscall`. Both are matched by `code`; `ABORT_ERR` deliberately drops the `ERR_` prefix to match the web's `AbortError`.
- Why can't you test a caught value with err instanceof SystemError?The documentation describes a `SystemError` shape, but Node's public modules export no such constructor, and the instances themselves report `Error` as their constructor. Detect a system error by its properties instead: a string `code`, a numeric `errno` and a `syscall`.
- Match the failure with err.message.includes('no such file').
- Compare err.errno with a fixed number such as -104 on every platform.
- System errors are instances of a SystemError class you can import.
- EMFILE means the file being opened does not exist.
- error.code can change in any minor or patch release of Node.