Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js util.getSystemErrorName() function

Reference for util.getSystemErrorName() in Node.js: turn a negative errno number such as -2 into ENOENT, plus getSystemErrorMap() and getSystemErrorMessage().

util.getSystemErrorName(err) converts a numeric system error code into its symbolic name, for example -2 into "ENOENT". The numbers come from libuv, the library under Node's I/O, and they are negative: an error is reported as the negative of the operating system's errno.

You meet these numbers in the errno property of system errors, in the results of low-level functions, and in some native add-ons. The name is what you would compare or log, because the numbers differ between operating systems while the names stay the same.

NODE
import { getSystemErrorName } from "node:util";

console.log(getSystemErrorName(-2)); // "ENOENT" on Linux

Try it

Node.js From an error object to a name

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 The full map and messages

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.

Syntax

NODE
util.getSystemErrorName(err: number): string
util.getSystemErrorMap(): Map<number, [name: string, message: string]>
util.getSystemErrorMessage(err: number): string
Name Description
err A negative integer error number as used by libuv.

Returns: getSystemErrorName() returns the name, or "Unknown system error -N" when the number is not known. getSystemErrorMap() returns a new Map from every known number to [name, message]. getSystemErrorMessage() returns the human-readable message and was added in a recent release (Node 23.1).

Errors: a non-number throws ERR_INVALID_ARG_TYPE. A number that is not a negative integer, for example 2, throws ERR_OUT_OF_RANGE.

Usage notes

  • Pass the negative number. getSystemErrorName(2) is a range error, not "ENOENT".
  • The numbers are platform specific. -2 is ENOENT on Linux, but other systems use different numbers for other names. Compare names, never raw numbers.
  • Most of the time you do not need this function: errors from fs, net and friends already have a code property with the name.
  • It is useful for values that arrive as plain numbers, such as an exit status mapped by a native layer or the result of low-level callbacks.
  • The map is rebuilt on each call to getSystemErrorMap(); keep the result if you query it repeatedly.
  • The messages are libuv's short descriptions (such as "no such file or directory"), not localized text.