Errors: custom types, cause, finally, and failing async work

throw accepts any value, but only an Error (or a subclass) carries a stack — the record of where it was created — and a name and message that logging tools understand. throw "not found" gives the catcher a bare string with no trace of where it came from. Always throw Error objects.

Your own error types

A subclass lets callers tell failures apart without parsing messages:

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

Set name — otherwise it is inherited as "Error" and every log line reads the same. Callers branch with instanceof, not on the message text.

cause: wrap without losing the original

When you catch a low-level error and throw a more meaningful one, pass the original as cause: new Error("config unreadable", { cause: err }). The new error describes what failed at your level; err.cause still holds the exact underlying failure for whoever debugs it.

1class ValidationError extends Error {2  constructor(field, message, options) {3    super(message, options);4    this.name = "ValidationError";5    this.field = field;6  }7}8 9function parsePort(text) {10  let value;11  try {12    value = JSON.parse(text).port;13  } catch (err) {14    throw new ValidationError("port", "config is not valid JSON", { cause: err });15  }16  if (!Number.isInteger(value)) {17    throw new ValidationError("port", `port must be an integer, got ${JSON.stringify(value)}`);18  }19  return value;20}21 22function describe(text) {23  try {24    return { port: parsePort(text) };25  } catch (err) {26    return {27      name: err.name,28      message: err.message,29      isValidation: err instanceof ValidationError,30      isError: err instanceof Error,31      causeName: err.cause ? err.cause.name : null,32      hasStack: typeof err.stack === "string",33    };34  }35}36 37export function run() {38  let thrownString;39  try {40    throw "not found";41  } catch (err) {42    thrownString = { type: typeof err, hasStack: typeof err?.stack === "string" };43  }44  return {45    good: describe('{"port": 8080}'),46    wrongType: describe('{"port": "8080"}'),47    notJson: describe("port=8080"),48    thrownString,49  };50}

Catch what you can handle

JavaScript has no typed catch clauses. A catch receives everything — your validation errors, but also a TypeError from a bug two calls down. Handle the cases you expect and rethrow the rest:

try {
  port = parsePort(text);
} catch (err) {
  if (!(err instanceof ValidationError)) throw err;   // not ours: let it go
  port = 8080;
}

A catch that logs and continues for every error turns real bugs into silently wrong results.

finally

finally runs whether the try returned, threw or completed normally — the place for cleanup such as closing a file or releasing a lock. It does not change the value being returned, unless it contains its own return, which replaces the result and even discards an error that was on its way out.

1export async function run() {2  const log = [];3 4  function readConfig() {5    try {6      log.push("try");7      return "value from try";8    } finally {9      log.push("finally (cleanup)");10    }11  }12 13  function swallow() {14    try {15      throw new Error("this error is lost");16    } finally {17      return "finally returned";18    }19  }20 21  async function failLater() {22    throw new Error("async failure");23  }24 25  const value = readConfig();26  const swallowed = swallow();27  let asyncCaught;28  try {29    await failLater();30  } catch (err) {31    asyncCaught = err.message;32  }33 34  return { log, value, swallowed, asyncCaught };35}

Async errors

Inside an async function a throw becomes a rejected promise, and an awaited rejection becomes a throw at the await (lesson 5). So the same try/catch works — as long as the promise is awaited inside the try. return task() without await hands the promise back before it settles, and a rejection then escapes the catch around it.

Common mistakes

• Catching everything and retrying or ignoring it. A bug such as a TypeError deserves to surface, not to be retried three times.
• Rethrowing a new error without cause. The original stack is gone, and whoever debugs it starts from your message alone.
• return inside finally. It overrides the try's result and swallows a thrown error, as the second example shows.
• return promise instead of inside a . The rejection happens after the has finished.