Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Concepts and Pitfalls

Node.js error codes

How to read and branch on the code property of Node.js errors: system codes such as ENOENT and EADDRINUSE, and Node's own ERR_ codes.

Almost every error that Node.js itself creates carries a code property: a short, stable, upper-case string. The message is meant for people and can be reworded between releases; the code is meant for programs. Whenever you need to decide what to do about a failure, branch on err.code, never on a piece of the message text.

There are two families. System error codes such as ENOENT or EADDRINUSE come from the operating system and are passed through unchanged. Node.js error codes start with ERR_ and are created by Node itself, for example ERR_INVALID_ARG_TYPE or ERR_STREAM_PREMATURE_CLOSE.

NODE
try {
  await fs.promises.readFile('missing.txt');
} catch (err) {
  if (err.code === 'ENOENT') console.log('no such file');
  else throw err;
}

Try it

Node.js Branching on err.code

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js System codes versus ERR_ codes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How codes work

Node attaches code as a plain property of the error object. For Node-generated errors, the name is the plain class name (TypeError, RangeError, Error) and the code appears in square brackets only in the stack header, for example TypeError [ERR_INVALID_ARG_TYPE]: .... Treat that header as decoration; read the property.

Frequent system codes

Code Typical meaning
ENOENT A path component does not exist.
EEXIST Something already exists at that path.
EISDIR / ENOTDIR A directory was used as a file, or the other way round.
EACCES / EPERM Permission denied (file mode) or operation not permitted.
ENOTEMPTY A directory you tried to remove still has entries.
EMFILE The process has too many open file descriptors.
EADDRINUSE Another socket already listens on that address and port.
ECONNREFUSED Nothing is listening at the target address.
ECONNRESET The other side closed the connection abruptly.
ETIMEDOUT A connection or operation timed out.
EPIPE Writing to a connection whose reader has gone away.

Frequent Node.js codes

Code Typical meaning
ERR_INVALID_ARG_TYPE An argument has the wrong type.
ERR_INVALID_ARG_VALUE Right type, unacceptable value.
ERR_OUT_OF_RANGE A number is outside the allowed range.
ERR_MODULE_NOT_FOUND An import specifier could not be resolved.
ERR_REQUIRE_ESM A require() hit an ES module that cannot be loaded this way.
ERR_STREAM_PREMATURE_CLOSE A stream ended before it finished.
ERR_UNHANDLED_ERROR An 'error' event with no listener.
ABORT_ERR An operation was cancelled through an AbortSignal.

Usage notes

  • Compare codes, not messages. Messages contain paths, numbers and wording that can change.
  • Re-throw what you do not understand. A handler for ENOENT should throw err for every other code, otherwise real bugs vanish.
  • System errors have extra fields (errno, syscall, path); see System errors.
  • Codes are documented per API. The ERR_ list is large and grows with releases; do not try to memorize it, look up the code you hit.
  • Do not invent look-alike codes for your own errors without a prefix. A prefix of your own (APP_NOT_FOUND) avoids clashing with Node's.
  • Some APIs use ABORT_ERR and an AbortError name for cancellation; treat it as an expected outcome rather than a failure.
  • Test with the code, for example assert.rejects(promise, { code: 'ENOENT' }).