skip to content

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?

level: middleimportance: must knowfreq 60%

answer

  1. from the operating system, via libuv
  2. string label versus free text
  3. a number that varies by platform
  4. syscall, path, address, port
  5. messages change in any release

basics

~20 s

A 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 s

When 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 lines
javascript
import { 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

for a junior

Recall that a system error carries a string code like ENOENT or ECONNRESET, and that code is what you compare, not the message.

for a middle

Explain the full set of properties, errno, syscall, path, address and port, why errno is platform-dependent, and what the common codes mean.

for a senior

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.

for a principal

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.