TypeError, ReferenceError and Friends

JavaScript has seven built-in error constructors, and each one signals a different category of mistake.

A TypeError means a value was of the wrong type for the operation. A ReferenceError means the name does not exist in any enclosing scope. A RangeError means the value had the right type but was out of the allowed range, such as an array length that cannot be negative. A SyntaxError means the code could not be parsed, and it is thrown before your code runs at all. A EvalError relates to the eval function and is very rare. A URIError means a malformed URI was passed to the encoding and decoding functions. And an AggregateError was added later to carry several errors at once, and it is what the promise combinators use internally.

All of them extend the base Error type, so instanceof Error is true for every one of them. To tell them apart you look at the name property, or you check the constructor. The name property is the more reliable of the two, because a custom error class can set its own name.

One thing to be clear about. A SyntaxError cannot be caught by a try and catch around the code that contains it, because the parse happens before the code starts running. You can only catch it with a try and catch around an eval call, which is exactly why dynamic evaluation is best avoided in production.

An error object carries more than a message. The useful properties are the name, the message, the stack, and the cause, which links the error to whatever failed underneath it.

class AppError extends Error {
  constructor(message, cause) {
    super(message);
    this.name = "AppError";
    this.cause = cause;
  }
}

// Inspect an error properly.
function describe(err) {
  return {
    name: err.name,
    message: err.message,
    isError: err instanceof Error,
    cause: err.cause ? err.cause.message : null,
  };
}

const low = new Error("disk full");
const high = new AppError("could not save profile", low);

console.log(describe(high));
// { name: "AppError", message: "could not save profile", isError: true, cause: "disk full" }
console.log(describe(low).cause);   // null

// Errors can also be aggregated.
const aggregate = new AggregateError([low, new Error("timeout")], "several failures");
console.log(aggregate.errors.length);   // 2
console.log(aggregate.message);         // "several failures"

The stack property is the one that earns its keep in practice. It records the call stack at the point the error was created, which is what you look at when you are trying to work out where something went wrong. Note that the stack is captured when the error is constructed, so if you create an error and throw it later the stack points at the creation site rather than the throw site.

The cause property is newer and worth adopting. It lets you wrap a low level failure in a higher level one without losing the original, so the log shows both the message your user cares about and the underlying reason. You set it by passing an options object as the second argument to the Error constructor.

One caution. Because any value can be thrown, you should never assume the caught value is an Error object. Code that reads err.message without checking will fail confusingly when someone throws a string, which happens often enough in older code that defensive code is worth it.

Three of the common error types are easy to trigger deliberately, which makes them a good way to check that your error handling actually works.

// A ReferenceError - the name does not exist.
try {
  console.log(notDefinedAnywhere);
} catch (err) {
  console.log(err.name);    // "ReferenceError"
}

// A TypeError - the value exists but does not support the operation.
try {
  const value = null;
  value.toUpperCase();
} catch (err) {
  console.log(err.name);    // "TypeError"
}

// A RangeError - right type, wrong value.
try {
  new Array(-1);
} catch (err) {
  console.log(err.name);    // "RangeError"
}

// A SyntaxError cannot be caught around the code that contains it,
// because the parse happens before any code runs.
try {
  eval("const =");
} catch (err) {
  console.log(err.name);    // "SyntaxError"
}

The ReferenceError example is the one you will actually hit in production, and it has a close relative. Reading a variable that was never assigned gives you the empty value rather than an error, but reading a name that was never declared at all throws. That difference trips people up because the two mistakes look the same in the source.

The TypeError example is the other big one. It happens whenever a value is of a type that does not support the operation you asked for, such as calling a method on a missing property or passing a plain object where an array was expected.

The RangeError example shows the third category, where the type is right but the value is not allowed. The classic cases are an invalid array length and a number outside the valid range for a numeric conversion.

The eval line is there to make one point clearly. A syntax error in the file itself is not catchable, because the parser rejects the file before a single statement runs. Wrapping the offending code in a try and catch does not help.