Node.js Reference ยท Concepts and Pitfalls
System errors in Node.js
What the errno, code, syscall, path and dest properties of Node.js system errors mean, how to read them, and how to map error numbers to names.
A system error is what Node.js raises when a call into the operating system fails: opening a missing file, binding a taken port, connecting to a closed one. These errors are ordinary Error objects with a handful of extra properties that describe exactly what went wrong and where.
The message already combines those properties into one line (ENOENT: no such file or directory, open 'x.txt'), but the properties let your code react precisely, and let your logs stay structured.
err.code // 'ENOENT' err.syscall // 'open' err.path // 'x.txt' err.errno // a number, negative on POSIX systems
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.
The properties
| Property | Meaning |
|---|---|
code |
The symbolic name such as ENOENT. This is the one to branch on. |
errno |
The numeric error from the OS. On Linux and macOS it is the negated POSIX number; on Windows it is the libuv error number. Do not compare it across platforms. |
syscall |
The failing operation: open, read, mkdir, rename, listen, connect, bind, and so on. |
path |
The file system path involved, when there is one. |
dest |
The second path of two-path calls such as rename, copyFile, link and symlink. |
address / port |
The network endpoint of a failed connect or bind. |
info |
Extra detail some DNS and network errors add. |
The numbers differ by platform, which is why code is the portable key: ENOENT is the same word everywhere, while its number is not guaranteed to be.
Usage notes
- Not every property is always present.
pathexists only for file operations,addressandportonly for network ones. Read them defensively. - Paths can be sensitive. The message includes the path. Do not send raw system errors to HTTP clients; log them and answer with a generic message.
- Synchronous and promise APIs report the same fields. Callback APIs pass the same error as the first argument.
util.getSystemErrorName()andutil.getSystemErrorMap()translate numbers into names; they expect the negative value Node reports on POSIX.os.constants.errnoholds the platform's own numbers by name.EMFILEandENFILEmean you ran out of descriptors. Close what you open, limit concurrency, and avoid opening thousands of files at once.ECONNRESETandEPIPEare normal for network programs. Handle them as events on the socket rather than crashing.- DNS failures use their own codes such as
ENOTFOUNDand carryhostname.