Throwing & custom errors

When something goes wrong, say so clearly

In the try, catch & finally lesson, you learned how to catch an error and clean up afterward. This lesson is about the other side: how to create an error. A good error says exactly what went wrong, so the code that catches it knows what to do.

JavaScript uses throw when something goes wrong and the code can't go on as normal. You can throw any value. But most code throws an Error object, or an object made from your own class based on Error. Then every caught error has the same parts:

• name: what kind of error it is, like ValidationError.
• message: a short sentence that says what went wrong.
• stack: in most places, text that lists the lines that led to the error.
• cause: sometimes, an earlier error that led to this one.
• Any extra properties your app needs, like field.

Here is a first look at an error with all of these parts. Don't worry about cause yet; you'll learn it later in this lesson.

const original = new SyntaxError("Bad JSON");
const error = new Error("Could not load settings", { cause: original });
error.field = "settings";
console.log(error.cause.name);
console.log(JSON.stringify(error));
console.log(JSON.stringify({
  name: error.name,
  message: error.message,
  cause: error.cause.name,
  field: error.field,
}));

• Line 1 makes a SyntaxError. That is the kind of error JSON.parse throws for broken text.
• Line 2 makes a new error and keeps the first one as its cause.
• Line 3 adds an extra property, field.
• Line 4 reads the first error back through error.cause. It prints SyntaxError.
• Line 5 turns the error into JSON text and prints {"field":"settings"}.

Why only field? JSON.stringify copies only the properties that are marked as listable. On an error, name, message, and cause are not listable. The field you added is.

Lines 6 to 11 build a plain object by hand, so all four parts get copied. Do this when a log or a server reply needs the whole error.

A newer check, Error.isError, is not available everywhere yet. For example, Node 22 doesn't have it. So this lesson doesn't use it.

This lesson covers these, in order:

• throw
• your own error classes, made with extends Error
• error.cause
• wrapping errors
• AggregateError

A throw statement can throw any value: text, a number, an object, or an Error. This is good to know, because older code sometimes throws text or plain objects. But a value you are allowed to throw is not always easy to handle. First, see what throw does to the lines after it.

console.log("before");
throw new Error("No token");
console.log("after");

Line 1 runs and prints before. Line 2 makes an Error and throws it. JavaScript stops right there, so line 3 never runs. If a catch is around this code, the catch takes over. If not, JavaScript shows an "uncaught" error in the console.

Now step through the experiment below. Pick a value to throw. Then see exactly what the catch gets.

1function throwValue(kind) {2  if (kind === "text") throw "plain text";3  if (kind === "number") throw 42;4  if (kind === "object") throw { code: "E_BOX" };5  throw new Error("File is missing");6}7 8try {9  throwValue("error");Run10} catch (caught) {11  console.log(typeof caught);12  console.log(caught instanceof Error);13  console.log(caught instanceof Error ? caught.message : typeof caught === "object" ? JSON.stringify(caught) : caught);14}

Compare the results:

• With throw "plain text", the catch gets text.
• With throw 42, the catch gets a number.
• Only throw new Error("File is missing") gives the catch a real error object, with a message and a stack.

A custom error class is a name for one kind of problem, like "a form input is wrong". It doesn't make the program fail harder. It makes the problem easier to recognize. You already know extends and super from the class inheritance lesson. A custom error needs four small steps:

• Write extends Error, so your class is based on Error.
• Call super(message) before you use this. This lets Error set up the message and the stack.
• Set a clear name, like "ValidationError".
• Add properties that code can check, like field or statusCode.

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

const error = new ValidationError("email", "Email is required");
console.log(error.name, error.field, error.message);

• Line 3 calls super(message), so Error stores the message.
• Line 4 sets the name that logs will show.
• Line 5 stores which form field was wrong, so a form can highlight it.
• Line 9 makes the error.
• Line 10 reads three properties and prints ValidationError email Email is required.

class PaymentError extends Error {}
const error = new PaymentError("Card declined");
console.log(error.name);
console.log(String(error));

This class works, but it never sets a name. Line 3 prints Error. Line 4 prints Error: Card declined. Giving the class a new name does not change the error's name property. So a log can't tell that this was a payment problem.

class PaymentError extends Error {
  constructor(message) {
    super(message);
    this.name = "PaymentError";
  }
}
const error = new PaymentError("Card declined");
console.log(error.name);
console.log(String(error));

Line 3 still calls super(message), which stores the message and the stack. Line 4 sets this.name. Now line 8 prints PaymentError, and line 9 prints PaymentError: Card declined. A payment problem is easy to spot in a log.

The experiment below uses two classes:

• AppError is for any problem in the app. It extends Error.
• ValidationError is for a bad form input. It extends AppError.

Each class keeps its name in a static field called errorName. A static field belongs to the class itself, not to each object. Line 4 reads it with this.constructor.errorName, so each class gets its own name. Line 5 uses options?.statusCode ?? 500: the status code passed in, or 500 if there is none. The catch checks the more specific class, ValidationError, first.

1class AppError extends Error { static errorName = "AppError";2  constructor(message, options) {3    super(message, options);4    this.name = this.constructor.errorName;5    this.statusCode = options?.statusCode ?? 500;6  }7}8 9class ValidationError extends AppError { static errorName = "ValidationError";10  constructor(field, message) {11    super(message, { statusCode: 400 });12    this.field = field;13  }14}15 16function saveUser(input) {17  if (!input.email) throw new ValidationError("email", "Email is required");18  return "saved";19}20 21try {22  saveUser({});Run23} catch (error) {24  if (error instanceof ValidationError) {25    console.log("validation", error.field, error.statusCode);26  } else if (error instanceof AppError) {27    console.log("app", error.statusCode);28  }29}

instanceof checks whether an object was made by a class, or by a class that extends it. It looks at how the classes are linked. It does not read the text in error.name. So the name is for people reading logs, and the classes are what your code should check.

error.cause: keep the original error

Sometimes the error you want to report is not the first error that happened. Say your app loads a settings file. JSON.parse throws a SyntaxError, because the text is broken. But the useful message for your app is "Config file is not valid JSON".

That new error should do two things:

• say what your app was doing
• keep the original SyntaxError, so you can still see the details

Every Error constructor takes a second argument: an options object. Its cause property keeps the original error: new Error("Couldn't load profile", { cause: err }). Your own error classes can pass the same options object on to super.

A low-level error comes from a small built-in tool, like JSON.parse. It knows nothing about your app. To wrap an error means: catch it, then throw a new error with a clearer message for your app. The new error doesn't throw the old one away. It keeps it in cause.

1class ConfigError extends Error {2  constructor(message, options) {3    super(message, options);4    this.name = "ConfigError";5  }6}7 8function parseConfig(text) {9  try {10    return JSON.parse(text);11  } catch (error) {12    throw new ConfigError("Config file is not valid JSON", { cause: error });13  }14}15 16function causeChain(error) {17  const chain = [];18  let current = error;19  while (current instanceof Error) {20    chain.push(current.name + ": " + current.message);21    current = current.cause;22  }23  return chain;24}25 26try {27  parseConfig("{ bad json }");Run28} catch (error) {29  console.log(causeChain(error).join(" -> "));30}

Line 12 is the wrap. The outer catch on line 28 gets a ConfigError with a clear message, and error.cause still holds the original SyntaxError.

The causeChain function on lines 16 to 24 starts at the outer error. It follows .cause from each error to the next. So line 29 prints both errors:

• what the app was doing: ConfigError: Config file is not valid JSON
• what exactly broke: the SyntaxError from JSON.parse

cause makes a chain: this error happened because of that one. AggregateError makes a bundle: several separate errors happened during one job. AggregateError is built into JavaScript. It has:

• a message that sums up the problem
• an errors array that holds each separate error

1const errors = [2  new Error("Email is required"),3  new Error("Must be 13 or older"),4];5const problem = new AggregateError(errors, "User has validation errors");6console.log(problem.name);7console.log(problem.message);8console.log(problem.errors.length);

In the code, lines 1 to 4 make an array of two errors. Line 5 puts them in one AggregateError, called problem. Lines 6 to 8 print its name, its message, and how many errors it holds: AggregateError, User has validation errors, and 2.

Here you make an AggregateError yourself, from an array of errors and a message. Promises can make one too. A promise is a value that arrives later, or fails. You'll learn promises later in the course.

Promise.any([
  Promise.reject(new Error("Primary server failed")),
  Promise.reject(new Error("Backup server failed")),
]).catch((error) => {
  console.log(error.name);
  console.log(error.errors.length);
});

Promise.any waits for the first promise that succeeds. Here both promises fail (the word for this is "reject"). So its catch gets an AggregateError, with one error in errors for each failed promise. Line 5 prints AggregateError, and line 6 prints 2.

Designing useful errors

A good error helps two readers at once:

• your code, which decides what to do next
• a person, who reads the log

Give each reader its own part. The message is for people. Extra properties are for code. The table below lists the parts of a useful error. Read each row as: this part, its job, an example.

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

const response = { ok: false, status: 404 };
try {
  if (!response.ok) throw new HttpError(response.status, "Profile not found");
} catch (error) {
  console.log(error.name, error.status, error.message);
}

On line 9, response is a made-up object. It stands in for a real reply from fetch. Its status is 404, which means "not found". Line 11 throws an HttpError that keeps that number. Line 13 prints HttpError 404 Profile not found.

Real code could check error.status. It could show a "not found" page for 404, but a "try again" message when the server itself fails.

function loadProfile() {
  throw Object.assign(new Error("Profile not found"), { code: "PROFILE_NOT_FOUND" });
}

try {
  loadProfile();
} catch (error) {
  if (error.code === "PROFILE_NOT_FOUND") console.log("show sign-in");
}

Line 2 throws a normal Error. Object.assign copies an extra code property onto it. Line 8 checks the code and prints show sign-in.

A code string helps when the error comes from somewhere else, like a server reply. A class can't travel inside a reply, but text can. Write down the codes you use, and plan what to do for codes you don't know.

const error = { code: "TIMEOUT" };
if (error.code === "PROFILE_NOT_FOUND") {
  console.log("show sign-in");
} else {
  console.log("retry later");
}

TIMEOUT is not a code this check knows. So the else branch runs and prints retry later.

Code strings are easy to send anywhere. Inside one program, a class check is stronger. A typo in a class name causes an error you will notice. A typo in a code string just fails to match.

Now sort some messages. A good message says what failed, and often how to fix it. A bad message makes the next developer guess.

Common misconceptions

Key takeaways

• throw stops the code until a catch takes over.
• Throw Error objects. Then the catch gets a name, a message, and a stack, and instanceof works.
• Your own classes, like ValidationError, let a catch tell problems apart.
• error.cause keeps the original error behind a clearer summary error.
• AggregateError holds several separate errors in one object.

Final definition: throw is how JavaScript reports that something went wrong. Custom errors say what kind of problem it was, carry useful facts, and keep the original error.

Up next: Error handling strategies.