Building Custom Error Classes

You extend the built-in Error class, call its constructor with the message, and set the name property so that the error identifies itself correctly in logs and in catch blocks.

class ValidationError extends Error {
  constructor(field, message) {
    super(message);
    this.name = "ValidationError";
    this.field = field;
    this.isValidationError = true;
  }
}

try {
  throw new ValidationError("email", "That address is not valid");
} catch (err) {
  console.log(err instanceof Error);           // true
  console.log(err instanceof ValidationError);  // true
  console.log(err.name);                      // "ValidationError"
  console.log(err.field);                     // "email"
  console.log(err.message);                   // "That address is not valid"
}

The super call is not optional. The Error constructor sets up the message and the stack, and if you skip it the error will have no useful message and no stack trace at all. Calling it first, before you touch this, is also required by the language when you are extending a built-in class.

Setting the name matters because that is what the catch block and the log formatter read. The name property on the Error prototype is inherited as Error, so a subclass that does not set it will be reported as a plain Error and you lose the ability to tell your error types apart at runtime.

The extra properties are your own domain data. The field in the example is what makes the error useful in a form handler, where you can put the message next to the right input. You can also add a status code, a machine readable code, or a list of problems, and the catch block can then decide what to do based on those rather than by matching on the message text.

It attaches the error that caused this one, so the chain of failures is preserved instead of being flattened into a single message.

// The cause option keeps the original error.
try {
  try {
    JSON.parse("{oops");
  } catch (err) {
    throw new Error("Could not read the config file", { cause: err });
  }
} catch (err) {
  console.log(err.message);                        // "Could not read the config file"
  console.log(err.cause instanceof SyntaxError);   // true
  console.log(typeof err.cause.stack);             // "string"
}

// The cause works for a custom error class too.
class AppError extends Error {
  constructor(message, cause) {
    super(message, { cause });
    this.name = "AppError";
  }
}

const wrapped = new AppError("could not load settings", new Error("network down"));
console.log(wrapped.cause.message);   // "network down"

Without a cause, a wrapper either loses the original error entirely or has to paste its message into its own, which is where error messages that repeat themselves come from. With the cause, both survive, and the outer error can talk about what your layer was doing while the inner error explains what actually broke.

You can also set the cause by hand after creating the error, which is what you have to do on runtimes that predate the option. And you can read the cause of any error, including the ones you did not create, because the property is part of the standard shape of an Error.

One thing to know about how it is usually used. The cause property is not automatically part of the message, so if you log the error with a formatter that only prints the message, you will lose the chain. A logging setup that understands errors should walk the cause chain and print each link, which is exactly what structured error reporting tools do.