Errors & Error Handling

// Standard JavaScript errors and what raises them
const attempts = {
  ReferenceError: () => missingVariable,
  TypeError: () => null.title,
  RangeError: () => new Array(-1),
  SyntaxError: () => JSON.parse('{ "title": '),
  URIError: () => decodeURIComponent('%'),
};

for (const [expected, run] of Object.entries(attempts)) {
  try {
    run();
  } catch (err) {
    console.log(`${expected.padEnd(14)} -> ${err.name}: ${err.message}`);
  }
}

ReferenceError -> ReferenceError: missingVariable is not defined
TypeError      -> TypeError: Cannot read properties of null (reading 'title')
RangeError     -> RangeError: Invalid array length
SyntaxError    -> SyntaxError: Unexpected end of JSON input
URIError       -> URIError: URI malformed

// The four ways Node.js reports an error
import { readFile as readFileCb } from 'node:fs';
import { readFile } from 'node:fs/promises';
import { readFileSync } from 'node:fs';
import { EventEmitter } from 'node:events';

const missing = new URL('./no-such-file.json', import.meta.url);

// 1. Synchronous API: throw
try {
  readFileSync(missing);
} catch (err) {
  console.log('throw     ', err.code);
}

// 2. Callback API: error first
readFileCb(missing, (err) => {
  console.log('callback  ', err?.code);
});

// 3. Promise API: rejection
try {
  await readFile(missing);
} catch (err) {
  console.log('promise   ', err.code);
}

// 4. EventEmitter: 'error' event
const emitter = new EventEmitter();
emitter.on('error', (err) => console.log('event     ', err.message));
emitter.emit('error', new Error('connection lost'));

// Without a listener the same emit throws
try {
  new EventEmitter().emit('error', new Error('nobody is listening'));
} catch (err) {
  console.log('no listener', err.message);
}
try {
  new EventEmitter().emit('error', 'a plain string');
} catch (err) {
  console.log('non-Error ', err.code, '|', err.context);
}

throw      ENOENT
callback   ENOENT
promise    ENOENT
event      connection lost
no listener nobody is listening
non-Error  ERR_UNHANDLED_ERROR | a plain string

// Streams and pipelines: errors travel through the 'error' event or the promise
import { pipeline } from 'node:stream/promises';
import { Readable, Transform } from 'node:stream';

const failing = new Transform({
  transform(chunk, encoding, callback) {
    callback(new Error('bad row'));
  },
});

try {
  await pipeline(Readable.from(['a,b\n', 'c,d\n']), failing, async function (source) {
    for await (const chunk of source) console.log(String(chunk));
  });
} catch (err) {
  console.log('pipeline rejected:', err.message);
}

// A stream that ends without an error but too early
const early = new Readable({ read() {} });
setImmediate(() => early.destroy());
try {
  await pipeline(early, async function (source) { for await (const _ of source); });
} catch (err) {
  console.log(err.code);
}

pipeline rejected: bad row
ERR_STREAM_PREMATURE_CLOSE

// System errors carry code, errno, syscall and path
import { readFile, mkdir, rmdir } from 'node:fs/promises';
import { getSystemErrorName, getSystemErrorMessage } from 'node:util';

try {
  await readFile('/definitely/not/here.txt', 'utf8');
} catch (err) {
  console.log(err instanceof Error, err.constructor.name);
  console.log({
    code: err.code,
    errno: err.errno,
    syscall: err.syscall,
    path: err.path,
    name: getSystemErrorName(err.errno),
    text: getSystemErrorMessage(err.errno),
  });
  console.log(err.message);
}

try {
  await readFile(new URL('.', import.meta.url));
} catch (err) {
  console.log(err.code, err.syscall); // EISDIR
}

try {
  await mkdir(new URL('.', import.meta.url));
} catch (err) {
  console.log(err.code, err.syscall); // EEXIST
}
try {
  await rmdir(new URL('.', import.meta.url));
} catch (err) {
  console.log(err.code, err.syscall); // ENOTEMPTY
}

true Error
{
  code: 'ENOENT',
  errno: -2,
  syscall: 'open',
  path: '/definitely/not/here.txt',
  name: 'ENOENT',
  text: 'no such file or directory'
}
ENOENT: no such file or directory, open '/definitely/not/here.txt'
EISDIR read
EEXIST mkdir
ENOTEMPTY rmdir

// The Node.js error codes: match on code, never on message
import { readFileSync } from 'node:fs';
import { writeFile, rm } from 'node:fs/promises';
import { Buffer } from 'node:buffer';

const odd = new URL('./data.xyz', import.meta.url);
await writeFile(odd, 'x');

const cases = {
  'wrong type': () => readFileSync({}),
  'bad value': () => readFileSync('books\0.json'),
  'out of range': () => Buffer.alloc(8).readUInt32LE(6),
  'unknown encoding': () => Buffer.from('ff', 'rot13'),
  'invalid URL': () => new URL('/relative'),
  'missing module': () => import('./does-not-exist.mjs'),
  'unknown extension': () => import(odd),
};

for (const [label, run] of Object.entries(cases)) {
  try {
    await run();
  } catch (err) {
    console.log(`${label.padEnd(18)} ${String(err.code).padEnd(26)} ${err.name}`);
  }
}
await rm(odd);

wrong type         ERR_INVALID_ARG_TYPE       TypeError
bad value          ERR_INVALID_ARG_VALUE      TypeError
out of range       ERR_OUT_OF_RANGE           RangeError
unknown encoding   ERR_UNKNOWN_ENCODING       TypeError
invalid URL        ERR_INVALID_URL            TypeError
missing module     ERR_MODULE_NOT_FOUND       Error
unknown extension  ERR_UNKNOWN_FILE_EXTENSION TypeError

// Match on error.code, not on the message
import { readFile } from 'node:fs/promises';

async function readConfig(path) {
  try {
    return JSON.parse(await readFile(path, 'utf8'));
  } catch (err) {
    switch (err.code) {
      case 'ENOENT':
        return {}; // no config file is a normal situation
      case 'EACCES':
      case 'EISDIR':
        throw new Error(`Cannot read ${path}`, { cause: err });
      default:
        throw err; // includes SyntaxError from a broken file, which has no code
    }
  }
}

console.log(await readConfig(new URL('./nope.json', import.meta.url)));
try {
  await readConfig('/');
} catch (err) {
  console.log(err.message, '<-', err.cause.code);
}

{}
Cannot read / <- EISDIR

// A custom error hierarchy for the Bookshelf API
export class AppError extends Error {
  constructor(message, { code = 'APP_ERROR', status = 500, expose = false, cause } = {}) {
    super(message, { cause });
    this.name = new.target.name;
    this.code = code;
    this.status = status;
    this.expose = expose;
    Error.captureStackTrace?.(this, new.target);
  }

  toJSON() {
    return { name: this.name, code: this.code, message: this.expose ? this.message : 'Internal error' };
  }
}

export class NotFoundError extends AppError {
  constructor(resource, id, options) {
    super(`${resource} ${id} was not found`, { code: 'NOT_FOUND', status: 404, expose: true, ...options });
    this.resource = resource;
    this.id = id;
  }
}

export class ValidationError extends AppError {
  constructor(problems) {
    super('The request is invalid', { code: 'VALIDATION', status: 400, expose: true });
    this.problems = problems;
  }
}

const err = new NotFoundError('book', 42);
console.log(err instanceof NotFoundError, err instanceof AppError, err instanceof Error);
console.log(err.name, err.code, err.status);
console.log(JSON.stringify(err));
console.log(err.stack.split('\n')[0]);
console.log(Object.prototype.toString.call(err));

true true true
NotFoundError NOT_FOUND 404
{"name":"NotFoundError","code":"NOT_FOUND","message":"book 42 was not found"}
NotFoundError: book 42 was not found
[object Error]

// Error cause chains
import { readFile } from 'node:fs/promises';
import { inspect } from 'node:util';

Error.stackTraceLimit = 0; // keep this demo output short

class RepositoryError extends Error {}

async function loadBook(id) {
  try {
    return JSON.parse(await readFile(`/no/such/books/${id}.json`, 'utf8'));
  } catch (cause) {
    throw new RepositoryError(`Could not load book ${id}`, { cause });
  }
}

try {
  await loadBook(7);
} catch (err) {
  console.log(err.message);
  console.log(err.cause.code);
  console.log(Object.hasOwn(err, 'cause'), Object.keys(err));

  // Walk the chain
  for (let e = err; e; e = e.cause) {
    console.log(' ->', e.constructor.name, e.code ?? '');
  }
  console.log(inspect(err));
}

Could not load book 7
ENOENT
true []
 -> RepositoryError
 -> Error ENOENT
[RepositoryError: Could not load book 7] {
  [cause]: [Error: ENOENT: no such file or directory, open '/no/such/books/7.json'] {
    errno: -2,
    code: 'ENOENT',
    syscall: 'open',
    path: '/no/such/books/7.json'
  }
}

// AggregateError: several failures reported as one
const results = await Promise.allSettled([
  Promise.resolve('book 1'),
  Promise.reject(new Error('book 2 failed')),
  Promise.reject(new TypeError('book 3 failed')),
]);
const failures = results.filter((r) => r.status === 'rejected').map((r) => r.reason);
console.log(failures.length, 'failed of', results.length);

try {
  await Promise.any([
    Promise.reject(new Error('mirror A down')),
    Promise.reject(new Error('mirror B down')),
  ]);
} catch (err) {
  console.log(err instanceof AggregateError, err.name, '|', err.message);
  console.log(err.errors.map((e) => e.message));
}

// Throw your own, and build one from the failures above
const combined = new AggregateError(failures, 'Import finished with errors', {
  cause: new Error('nightly job'),
});
console.log(combined.errors.length, combined.cause.message);

2 failed of 3
true AggregateError | All promises were rejected
[ 'mirror A down', 'mirror B down' ]
2 nightly job

// Error.isError versus instanceof (Node.js 24 and later)
if (typeof Error.isError !== 'function') throw new Error('Error.isError needs Node.js 24 or later');
import vm from 'node:vm';

const foreign = vm.runInNewContext('new Error("from another realm")');
console.log(foreign instanceof Error);          // false: different Error constructor
console.log(Error.isError(foreign));            // true
console.log(Error.isError(new DOMException('x', 'AbortError')));
console.log(Error.isError({ name: 'Error', message: 'fake', stack: '' }));
console.log(Error.isError(Object.create(Error.prototype)));
console.log(Object.prototype.toString.call(foreign));

false
true
true
false
false
[object Error]

// Operational errors are handled; programmer errors are bugs
import { readFile } from 'node:fs/promises';

class ValidationError extends Error {
  name = 'ValidationError';
  operational = true;                 // our own marker for expected, recoverable failures
}

const OPERATIONAL_CODES = new Set([
  'ENOENT', 'EACCES', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EADDRINUSE', 'EPIPE',
]);

function isOperational(err) {
  if (err?.operational === true) return true;
  if (err?.name === 'AbortError') return true;
  return OPERATIONAL_CODES.has(err?.code);
}

for (const run of [
  () => readFile('/no/such/file'),                 // the world is not as expected
  () => { throw new ValidationError('title is required'); },
  () => { const book = null; return book.title; }, // a bug
]) {
  try {
    await run();
  } catch (err) {
    console.log(err.name.padEnd(16), isOperational(err) ? 'operational -> handle' : 'programmer  -> crash');
  }
}

Error            operational -> handle
ValidationError  operational -> handle
TypeError        programmer  -> crash

// Rethrowing: catch what you can handle, let everything else propagate
import { readFile } from 'node:fs/promises';

class ConfigError extends Error {
  name = 'ConfigError';
}

async function loadSettings(path) {
  let text;
  try {
    text = await readFile(path, 'utf8');
  } catch (err) {
    if (err.code === 'ENOENT') return { port: 3000 };   // expected: use defaults
    throw err;                                          // unexpected: do not swallow
  }
  try {
    return JSON.parse(text);
  } catch (err) {
    // Add context, keep the original as cause, and keep the stack of the original
    throw new ConfigError(`Settings file ${path} is not valid JSON`, { cause: err });
  }
}

console.log(await loadSettings('/no/such/settings.json'));
try {
  await loadSettings(new URL(import.meta.url).pathname);   // this .mjs file is not JSON
} catch (err) {
  console.log(err.name, '|', err.message.replace(/\/.*\//, '…/'), '|', err.cause.name);
}

// finally runs on every path; do not return or throw from it
function withCleanup() {
  try {
    throw new Error('first');
  } finally {
    console.log('cleanup runs');
  }
}
try { withCleanup(); } catch (err) { console.log('still got:', err.message); }

{ port: 3000 }
ConfigError | Settings file …/d2.mjs is not valid JSON | SyntaxError
cleanup runs
still got: first

// AssertionError anatomy and strict diffs
import assert from 'node:assert/strict';

try {
  assert.deepStrictEqual({ title: 'Dune', pages: 412 }, { title: 'Dune', pages: 421 });
} catch (err) {
  console.log(err.name, err.code, err.operator, err.generatedMessage);
  console.log(err.actual, err.expected);
  console.log(err.message);
}

AssertionError ERR_ASSERTION deepStrictEqual true
{ title: 'Dune', pages: 412 } { title: 'Dune', pages: 421 }
Expected values to be strictly deep-equal:
+ actual - expected

  {
+   pages: 412,
-   pages: 421,
    title: 'Dune'
  }

// assert.throws and assert.rejects validate the error, not only that something was thrown
import assert from 'node:assert/strict';
import { readFile } from 'node:fs/promises';

assert.throws(() => JSON.parse('{'), SyntaxError);
assert.throws(() => Buffer.alloc(-1), { code: 'ERR_OUT_OF_RANGE', name: 'RangeError' });
assert.throws(() => new URL('/x'), /Invalid URL/);

await assert.rejects(readFile('/no/such/file'), { code: 'ENOENT', syscall: 'open' });
await assert.rejects(Promise.reject(new TypeError('x')), (err) => {
  assert.equal(err.name, 'TypeError');
  return true;
});

// assert.throws fails if nothing is thrown
try {
  assert.throws(() => {}, Error);
} catch (err) {
  console.log(err.code, '|', err.message.split('\n')[0]);
}

// assert.ifError passes null/undefined and rethrows anything else
assert.ifError(null);
try {
  assert.ifError(new Error('callback failed'));
} catch (err) {
  console.log(err.code, '|', err.message.split('\n')[0]);
}
console.log('all assertions passed');

ERR_ASSERTION | Missing expected exception (Error).
ERR_ASSERTION | ifError got unwanted exception: callback failed
all assertions passed

// Custom messages: string, Error instance, or a function evaluated only on failure
import assert from 'node:assert/strict';
import legacy from 'node:assert';

const first = (err) => err.message.split('\n')[0];

try { assert.equal(1, 2, 'pages must match'); } catch (err) { console.log(first(err), err.generatedMessage); }
try { assert.equal(1, 2, new RangeError('thrown as is')); } catch (err) { console.log(err.name, err.message); }
try { assert.equal(1, 2, (actual, expected) => `wanted ${expected}, got ${actual}`); } catch (err) { console.log(first(err)); }

// Subset comparison
assert.partialDeepStrictEqual({ id: 1, title: 'Dune', tags: ['sf', 'classic'] }, { title: 'Dune', tags: ['sf'] });
console.log('partial match ok');

// Legacy mode compares with ==, strict mode with Object.is
legacy.equal('1', 1);
try { assert.equal('1', 1); } catch (err) { console.log('strict mode:', err.code); }

pages must match false
RangeError thrown as is
wanted 2, got 1
partial match ok
strict mode: ERR_ASSERTION

// Assertions are not input validation, and assertion errors are programmer errors
import assert from 'node:assert/strict';

function applyDiscount(price, percent) {
  assert(Number.isFinite(price) && price >= 0, 'price must be a non-negative number');
  assert(percent >= 0 && percent <= 100, `percent out of range: ${percent}`);
  return price * (1 - percent / 100);
}

console.log(applyDiscount(20, 25));
try {
  applyDiscount(20, 125);
} catch (err) {
  console.log(err instanceof assert.AssertionError, err.code, '|', err.message);
}

15
true ERR_ASSERTION | percent out of range: 125