Throwing errors with useful messages

Understanding Throwing errors with useful messages

`throw` accepts any value, but only an Error object carries a `name`, a `message`, and a stack snapshot taken where it was constructed. Whatever you pass becomes the value the nearest `catch` receives, and in most real systems that catch does one thing: it writes `err.message` into a log line, a toast, or a bug report. By the time a human reads that line, the variables, the request, and the loop index are gone. So write the message for that reader: one sentence, no surrounding context available.

A message earns its keep by answering three questions: which operation refused, what it required, and what it actually got. "Invalid input" answers none of them, while `setVolume: level must be between 0 and 100, got 120` answers all three and needs no follow-up question. The constructor adds a fourth piece for free: `TypeError` means the value was the wrong kind, `RangeError` means it was the right kind but outside the allowed span, and plain `Error` covers everything else. Since the name is printed in front of the message, do not repeat the category word inside the text.

Because `throw` unwinds the function immediately, nothing after it runs, which makes the top of a function the cheapest place to check: the argument is still exactly as the caller passed it, so you can quote it verbatim. Interpolate deliberately, though, since `${value}` turns `{ id: 1 }` into `[object Object]` and makes `"5"` look identical to `5` — the precise confusion the message existed to remove. Use `typeof` plus `JSON.stringify` for small values, and type-with-length for huge or sensitive ones. Keep the fixed words of the message stable so that grepping the codebase for the sentence lands on the exact `throw`.

One message per failed rule beats one message covering several rules, because each `throw` can then state the specific bound it checked instead of a vague summary of all of them.

function describe(value) {
  return typeof value === "string" ? JSON.stringify(value) : String(value);
}

function setVolume(level) {
  if (typeof level !== "number" || Number.isNaN(level)) {
    throw new TypeError(
      `setVolume: level must be a number, got ${typeof level} ${describe(level)}`
    );
  }
  if (level < 0 || level > 100) {
    throw new RangeError(`setVolume: level must be between 0 and 100, got ${level}`);
  }
  return level;
}

for (const input of ["80", NaN, 120, 80]) {
  try {
    console.log("ok:", setVolume(input));
  } catch (err) {
    console.log(`${err.name}: ${err.message}`);
  }
}

Worked examples

function parseAge(text) {
  const years = Number(text);
  if (!Number.isInteger(years)) throw "bad age";
  return years;
}

try {
  parseAge("twelve");
} catch (err) {
  console.log(typeof err);
  console.log(err instanceof Error);
  console.log(err.message);
  console.log(err.stack);
}

const rows = [
  { id: "u1", email: "ada@example.com" },
  { id: "u2", email: "" },
];

function vagueCheck(row) {
  if (!row.email) throw new Error("Invalid input");
}

function usefulCheck(row, index) {
  if (!row.email) {
    throw new Error(`rows[${index}] (id=${row.id}): email must not be empty`);
  }
}

for (const check of [vagueCheck, usefulCheck]) {
  try {
    rows.forEach(check);
  } catch (err) {
    console.log(err.message);
  }
}

function requireApiKey(key) {
  if (typeof key !== "string" || !key.startsWith("sk_")) {
    const shown = String(key);
    throw new Error(
      `requireApiKey: key must be a string starting with "sk_", got ${typeof key} of length ${shown.length} starting "${shown.slice(0, 3)}"`
    );
  }
  return key;
}

try {
  requireApiKey("pk_live_9f3a2b7c1d");
} catch (err) {
  console.log(err.message);
}

Important notes

Common mistakes

Try it yourself