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.
try { await fs.promises.readFile('missing.txt'); } catch (err) { if (err.code === 'ENOENT') console.log('no such file'); else throw err; }
Try it
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.
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
ENOENTshouldthrow errfor 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_ERRand anAbortErrorname for cancellation; treat it as an expected outcome rather than a failure. - Test with the code, for example
assert.rejects(promise, { code: 'ENOENT' }).