Typing errors

Anything can be thrown

A checkout page charges a card, and the charge can fail. In JavaScript, throw can throw any value, not only Error objects (the try, catch & finally lesson covers both). This card code throws plain text, and the catch block expects an Error. First, look at it the way TypeScript saw it before version 4.4. The example turns off the flag useUnknownInCatchVariables, which the next section explains:

1function payWithCard(amount: number) {2  if (amount > 100) throw "Card declined";3  return `Paid $${amount}`;4}5 6try {7  console.log(payWithCard(120));8} catch (error) {9  //     ^?10  console.log(`Payment failed: ${error.message}`);11}

Line 2 throws the text "Card declined" when the amount is over 100. Line 7 pays 120, so it throws, and line 8 catches the text as error. The answer after the ^? on line 9 shows any, the type that turns checking off. So line 10 reads error.message with no complaint, and prints Payment failed: undefined: text has no message.

Now the same code with this site's normal settings, where strict is on:

1function payWithCard(amount: number) {2  if (amount > 100) throw "Card declined";3  return `Paid $${amount}`;4}5 6try {7  console.log(payWithCard(120));8} catch (error) {9  //     ^?10  console.log(`Payment failed: ${error.message}`);11}

The answer on line 9 is now unknown, and line 10 gets an error, on purpose: 'error' is of type 'unknown'. In plain words: "this could be anything, so check what it is before you read from it". The code still prints Payment failed: undefined if you run it. The error is TypeScript pointing at the bug before a customer sees it.

Why catch gives you unknown

TypeScript can't know what a try block might throw. A function's type says what it gives back, but nothing about what it throws, and any line can call code that throws text. So since version 4.4, the flag useUnknownInCatchVariables makes the catch variable unknown. strict turns it on, along with the other strict checks. (unknown is the type for "a value you haven't checked yet"; the any, unknown & never lesson covers it.)

You may write the type on a catch variable, but only unknown or any. This mistake is on purpose:

1try {2  JSON.parse("{ broken");3} catch (error: Error) {4  console.log(error.name);5}6 7try {8  JSON.parse("{ broken");9} catch (error: unknown) {10  console.log(error instanceof SyntaxError);11}

Line 2 parses broken JSON, which throws a SyntaxError. Line 3 says the error is an Error, and TypeScript refuses: Catch clause variable type annotation must be 'any' or 'unknown' if specified. In plain words: "I can't promise what was thrown, so I won't let you say it". Line 9 writes unknown, which is allowed and changes nothing. Line 10 checks with instanceof. When it runs, line 4 prints SyntaxError and line 10 prints true.

Promises are different. A promise that fails is "rejected", and .catch runs a callback with the reason (the Error handling with promises lesson covers this). TypeScript's own types give that reason the type any, and strict doesn't change it:

1async function payWithCard(amount: number): Promise<string> {2  if (amount > 100) throw "Card declined";3  return `Paid $${amount}`;4}5 6payWithCard(120).catch((error) => {7  //                    ^?8  console.log(`Payment failed: ${error.message}`);9});10 11payWithCard(120).catch((error: unknown) => {12  console.log(`Payment failed: ${String(error)}`);13});

Line 2 throws text again, so the promise from line 6 is rejected. The answer on line 7 shows error is any, so line 8 reads message with no complaint and prints Payment failed: undefined. Line 11 writes (error: unknown) itself, which TypeScript allows, and now it would ask for a check. Line 12 uses String, which works on any value, and prints Payment failed: Card declined. A linter rule such as typescript-eslint's use-unknown-in-catch-callback-variable asks for this on every .catch.

The table below lists every place a failure reaches your code. Read each row from left to right:

Narrowing an unknown error

To use an unknown error, narrow it: check what it is, so TypeScript knows more inside the check (the in & instanceof narrowing lesson covers instanceof). Try four ways to write line 9, and watch what TypeScript says and what prints:

1function payWithCard(amount: number) {2  if (amount > 100) throw "Card declined";3  return `Paid $${amount}`;4}5 6try {7  console.log(payWithCard(120));8} catch (error) {9  const message = error.message;10  console.log(`Payment failed: ${message}`);11}

Only two choices print the real reason. error as Error is a type assertion (the Type assertions lesson covers them): it removes the error by making a promise you can't keep, because the value is text. instanceof Error really checks, and String(error) works on any value. Most code does both, in one small function:

1function getErrorMessage(error: unknown): string {2  if (error instanceof Error) return error.message;3  if (typeof error === "string") return error;4  return "Something went wrong";5}6 7try {8  throw new Error("Card declined");9} catch (error) {10  console.log(getErrorMessage(error));11}

Line 1 takes unknown, so you can pass it any caught value without a check. Line 2 returns the message of a real Error, including every class that extends it, like TypeError. Line 3 returns text as it is. Line 4 covers everything else with a message you chose. The function always gives back a string, so the rest of the page never has to think about what was thrown.

Custom error classes

Sometimes a page needs more than a message, like the HTTP status of a failed request: 401 means "log in first", and 404 means "not found". A class that extends Error can carry it (the Throwing & custom errors lesson builds these in JavaScript, and Classes in TypeScript covers typing class fields):

1class HttpError extends Error {2  status: number;3 4  constructor(status: number, message: string) {5    super(message);6    this.name = "HttpError";7    this.status = status;8  }9}10 11async function loadCart(): Promise<string[]> {12  throw new HttpError(401, "Not logged in");13}14 15async function showCart() {16  try {17    console.log(await loadCart());18  } catch (error) {19    if (error instanceof HttpError) {20      console.log(error.status === 401 ? "Please log in" : `Error ${error.status}`);21      //          ^?22    } else {23      console.log("Could not load the cart");24    }25  }26}27 28showCart();

Line 1 makes HttpError, a kind of Error. Line 2 declares a status field that holds a number. Line 5 passes the message to Error with super. Line 6 sets name, so logs and stack traces say HttpError instead of Error. Line 7 stores the status. Line 12 is a stand-in for a server that answers 401.

Line 18 catches an unknown, and line 19 checks error instanceof HttpError. Inside that check, the answer on line 21 shows error is an HttpError, so line 20 can read error.status as a number. It prints Please log in.

An error can also carry the error that caused it. new Error(message, { cause }) wraps a low-level failure in a clearer one, and keeps the original:

1async function sendOrder(): Promise<number> {2  throw new Error("Network down");3}4 5async function checkout() {6  try {7    return await sendOrder();8  } catch (error) {9    throw new Error("Checkout failed", { cause: error });10  }11}12 13checkout().catch((error: unknown) => {14  if (!(error instanceof Error)) return;15  console.log(error.message);16  const cause = error.cause;17  //    ^?18  if (cause instanceof Error) console.log(`Because: ${cause.message}`);19});

Line 2 fails with Network down. Line 9 catches it and throws a new error with the first one as its cause. Line 13 catches the new error as unknown, and line 14 stops unless it's an Error. The answer on line 17 shows the cause is unknown too: any value can be passed as a cause. So line 18 checks it before reading its message. It prints Checkout failed, then Because: Network down.

Result types instead of throwing

A thrown error is invisible in a function's type. For failures you expect, like a customer typing "abc" as a quantity, you can return the failure as a value instead. A Result type is a union of a success and a failure, told apart by an ok field (the Discriminated unions lesson covers this pattern, and the Error handling strategies lesson compares it with throwing). This first use forgets to check, on purpose:

1type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };2 3function parseQuantity(text: string): Result<number, string> {4  const quantity = Number(text);5  if (Number.isInteger(quantity) && quantity > 0) return { ok: true, value: quantity };6  return { ok: false, error: `"${text}" is not a quantity` };7}8 9const result = parseQuantity("abc");10console.log(`Total: $${result.value * 4}`);

Line 1 defines Result once, with two type parameters: T for the value and E for the error (the Generic types & interfaces lesson covers them). Line 3 says parseQuantity gives back a number or a text error. Line 5 returns a success for a whole number above zero, and line 6 returns a failure for anything else. Line 10 reads result.value without checking, and TypeScript says Property 'value' does not exist on type 'Result<number, string>': a failure has no value. Run it, and it prints Total: $NaN.

1type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };2 3function parseQuantity(text: string): Result<number, string> {4  const quantity = Number(text);5  if (Number.isInteger(quantity) && quantity > 0) return { ok: true, value: quantity };6  return { ok: false, error: `"${text}" is not a quantity` };7}8 9const result = parseQuantity("abc");10if (result.ok) {11  console.log(`Total: $${result.value * 4}`);12} else {13  console.log(result.error);14  //                 ^?15}

Line 10 checks result.ok. Inside, result is the success, so line 11 can use value. In the else, it's the failure, and the answer on line 14 shows error is a string. It prints "abc" is not a quantity. With the text "3", it would print Total: $12.

The error type can be a union of codes, one for each failure the caller should handle (the Literal types lesson covers these), and it works the same in async code:

1type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };2type Cart = { items: number; total: number };3type CartError = "not-logged-in" | "server-down";4 5async function loadCart(loggedIn: boolean): Promise<Result<Cart, CartError>> {6  if (!loggedIn) return { ok: false, error: "not-logged-in" };7  return { ok: true, value: { items: 3, total: 12 } };8}9 10function errorText(error: CartError): string {11  switch (error) {12    case "not-logged-in":13      return "Please log in";14    case "server-down":15      return "Try again in a minute";16  }17}18 19async function showCart(loggedIn: boolean) {20  const result = await loadCart(loggedIn);21  console.log(result.ok ? `Total: $${result.value.total}` : errorText(result.error));22}23 24showCart(true).then(() => showCart(false));

Line 3 lists the two ways loading a cart can fail. Line 5 gives back a Promise of a Result, so the failure is in the type even across await (the Promises & async functions lesson covers Promise<T>). Lines 10 to 17 turn each code into a message with a switch. It has a case for every code, so TypeScript knows every path returns. Line 21 prints the total or the message: Total: $12 for a logged-in visitor, then Please log in. Add a third code to line 3, and TypeScript marks line 10 until errorText handles it (the Exhaustiveness checking lesson covers this); exercise 5 tries it.

The table below compares the two ways to fail. Read each row from left to right:

Handling a failed checkout

A real checkout uses both. The request code throws, as most libraries do. The page code catches once, turns each failure into a message, and returns a Result that the page has to check:

1class HttpError extends Error {2  status: number;3 4  constructor(status: number, message: string) {5    super(message);6    this.name = "HttpError";7    this.status = status;8  }9}10 11type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };12 13async function sendOrder(total: number): Promise<number> {14  if (total > 100) throw new HttpError(402, "Payment required");15  if (total < 0) throw "Bad total";16  return 7;17}18 19async function placeOrder(total: number): Promise<Result<number, string>> {20  try {21    return { ok: true, value: await sendOrder(total) };22  } catch (error) {23    if (error instanceof HttpError && error.status === 402) {24      return { ok: false, error: "Your card was declined" };25    }26    return { ok: false, error: "Something went wrong" };27  }28}29 30async function showOrders() {31  for (const total of [12, 120, -1]) {32    const result = await placeOrder(total);33    console.log(result.ok ? `Order ${result.value} placed` : result.error);34  }35}36 37showOrders();

Lines 1 to 9 are HttpError from before, and line 11 is Result. Lines 13 to 17 are a stand-in for the server: over 100 throws an HttpError with status 402, a total below zero throws plain text, and anything else gives back order number 7. Line 19 says placeOrder gives back a promise of a Result, never a thrown error. Line 21 tries the order. Line 23 turns a 402 into a clear message, and line 26 covers everything else, including the text.

Line 33 has to check result.ok before reading value. The code prints Order 7 placed, Your card was declined, and Something went wrong. Now sort some one-line snippets by what TypeScript says about them:

Common mix-ups

instanceof checks run in order, and TypeScript doesn't tell you when one hides another. This code has no type errors, and still takes the wrong branch:

1class HttpError extends Error {2  status = 404;3}4 5function report(error: unknown) {6  if (error instanceof Error) {7    console.log(`Something went wrong: ${error.message}`);8  } else if (error instanceof HttpError) {9    console.log(`Status ${error.status}`);10  }11}12 13report(new HttpError("Not found"));

Line 1 makes HttpError with a status of 404. Line 6 checks for any Error first, and an HttpError is an Error, so line 7 prints Something went wrong: Not found. Line 9 can never run. Check the most specific class first, as in & instanceof narrowing showed.

• "A caught error is always an Error." No. Any value can be thrown: text, objects, even undefined. That's why it's unknown.
• "catch (error: Error) tells TypeScript what was thrown." No. TypeScript only allows any or unknown there. Narrow inside the block.
• "error as Error is the same as checking." No. as checks nothing. Text thrown as an error still has no message.
• "strict makes .catch callbacks unknown too." No. A .catch callback's value is still any. Write (error: unknown) yourself.
• "A function's type says what it can throw." No. TypeScript has no type for thrown errors. Use a Result when callers must handle a failure.
• "Results replace throwing everywhere." No. Throw for bugs and failures nothing nearby can fix; return a Result for failures callers should expect.

Practice exercises

Each exercise is TypeScript. Press Edit & run on the starter code to try a fix: the errors update as you type, and the console shows what it prints. Try a guess first, then use the hints.

1try {2  JSON.parse("{ broken");3} catch (error) {4  console.log("Could not read the saved cart");5}

1try {2  JSON.parse("{ broken");3} catch (error) {4  //     ^?5  console.log("Could not read the saved cart");6}

function saveCart(items: number) {
  if (items > 50) throw new RangeError("Too many items");
}

try {
  saveCart(60);
} catch (error: RangeError) {
  console.log(error.message);
}

1function saveCart(items: number) {2  if (items > 50) throw new RangeError("Too many items");3}4 5try {6  saveCart(60);7} catch (error) {8  if (error instanceof RangeError) console.log(error.message);9}

1function applyCoupon(code: string) {2  if (code !== "TEA10") throw `Unknown coupon ${code}`;3  return 10;4}5 6try {7  applyCoupon("CAKE5");8} catch (error) {9  console.log(`Coupon failed: ${error.message}`);10}

1function applyCoupon(code: string) {2  if (code !== "TEA10") throw `Unknown coupon ${code}`;3  return 10;4}5 6try {7  applyCoupon("CAKE5");8} catch (error) {9  const message = error instanceof Error ? error.message : String(error);10  console.log(`Coupon failed: ${message}`);11}

1class HttpError extends Error {2  constructor(message: string) {3    super(message);4    this.name = "HttpError";5  }6}7 8try {9  throw new HttpError("Not found");10} catch (error) {11  if (error instanceof HttpError) console.log(`Status ${error.status}`);12}

1class HttpError extends Error {2  status: number;3 4  constructor(status: number, message: string) {5    super(message);6    this.name = "HttpError";7    this.status = status;8  }9}10 11try {12  throw new HttpError(404, "Not found");13} catch (error) {14  if (error instanceof HttpError) console.log(`Status ${error.status}`);15}

1type CartError = "not-logged-in" | "server-down" | "out-of-stock";2 3function errorText(error: CartError): string {4  switch (error) {5    case "not-logged-in":6      return "Please log in";7    case "server-down":8      return "Try again in a minute";9  }10}11 12console.log(errorText("out-of-stock"));

1type CartError = "not-logged-in" | "server-down" | "out-of-stock";2 3function errorText(error: CartError): string {4  switch (error) {5    case "not-logged-in":6      return "Please log in";7    case "server-down":8      return "Try again in a minute";9    case "out-of-stock":10      return "Sold out";11  }12}13 14console.log(errorText("out-of-stock"));

1async function sendOrder(): Promise<number> {2  throw new Error("Network down");3}4 5async function checkout() {6  try {7    return await sendOrder();8  } catch (error) {9    throw new Error("Checkout failed", { cause: error });10  }11}12 13checkout().catch((error: unknown) => {14  if (error instanceof Error) console.log(`${error.message}, because: ${error.cause.message}`);15});

1async function sendOrder(): Promise<number> {2  throw new Error("Network down");3}4 5async function checkout() {6  try {7    return await sendOrder();8  } catch (error) {9    throw new Error("Checkout failed", { cause: error });10  }11}12 13checkout().catch((error: unknown) => {14  if (error instanceof Error && error.cause instanceof Error) {15    console.log(`${error.message}, because: ${error.cause.message}`);16  }17});

Check your understanding

For each question, ask: what could have been thrown, and what does TypeScript know about it? The quiz shows its code without the checker, so the error list doesn't give the answers away.

Key takeaways

• Any value can be thrown, so with strict on, a catch variable is unknown.
• A catch variable can only be typed any or unknown, and a .catch callback's value is any unless you write unknown.
• Narrow with instanceof Error, and fall back to String(error) or a message you chose. Never use as Error as a check.
• Custom error classes carry typed fields like status. Check the most specific class first.
• Return a Result<T, E> for failures callers should expect, so TypeScript makes them check ok.

Coming next: Typing React components. It types the components that show these messages: props, children, and event handlers.