Skip to content
Tutorials Center
My learning

Topics

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.

NODE
err.code     // 'ENOENT'
err.syscall  // 'open'
err.path     // 'x.txt'
err.errno    // a number, negative on POSIX systems

Try it

Node.js Inspecting the properties

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 Names and numbers

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. path exists only for file operations, address and port only 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() and util.getSystemErrorMap() translate numbers into names; they expect the negative value Node reports on POSIX.
  • os.constants.errno holds the platform's own numbers by name.
  • EMFILE and ENFILE mean you ran out of descriptors. Close what you open, limit concurrency, and avoid opening thousands of files at once.
  • ECONNRESET and EPIPE are normal for network programs. Handle them as events on the socket rather than crashing.
  • DNS failures use their own codes such as ENOTFOUND and carry hostname.