try, catch & finally

Catching an error on purpose

JavaScript runs your code one statement after another. Sometimes a statement fails. Then JavaScript throws an error: it stops the current work and hands the error back to the code that called it. If no code deals with the error, the program stops and the console shows a red message.

You learned to read those messages in Reading error messages. In The call stack, you saw an error leave one function call after another. This lesson shows how to deal with an error on purpose, so your program can keep going. You use three blocks: try, catch, and finally.

Use try and catch when you know something might fail, and you know what to do if it does. For example:

• Reading text as JSON, a common text format for data. The text might be broken.
• Reading data saved in the browser. It might not be there.
• Checking a form. The user might type something wrong.

Don't wrap every line in try "just in case". A catch that hides errors you didn't expect makes bugs harder to find.

Here is the whole idea in one small program. The path array keeps a list of the blocks that ran, in order. Pick what happens inside try: it works, or it throws one of two errors. Then step through the run.

1function riskyFormat(text) {2  return text.toUpperCase();3}4 5const path = [];Run6let value = "not set";7 8try {9  path.push("try");10  value = riskyFormat("ok");11} catch (error) {12  path.push("catch " + error.name);13  value = "fallback";14} finally {15  path.push("finally");16}17 18console.log(path.join(" → "));19console.log(value);

First, the case where nothing goes wrong. try runs first. catch is skipped. finally still runs at the end.

try {
  console.log("try");
} catch {
  console.log("catch");
} finally {
  console.log("finally");
}

Line 2 prints try. Nothing throws, so the catch block on lines 3 and 4 never runs. Line 6 prints finally. The output is try, then finally.

Now a case where a line throws. JavaScript skips the rest of try, runs catch, and then runs finally.

try {
  console.log("try");
  throw new Error("sold out");
} catch (error) {
  console.log("catch: " + error.message);
} finally {
  console.log("finally");
}

Line 2 prints try. Line 3 uses throw to throw an error on purpose. new Error("sold out") makes an error object whose message is sold out. JavaScript stops try right there and jumps to catch on line 4. The variable error now holds the thrown error, so line 5 prints catch: sold out. Then line 7 prints finally.

1. No error: try runs, catch is skipped, and finally runs.
2. An error: try starts, a line throws, JavaScript jumps to catch, and then finally runs.
3. Leaving early: finally also runs when try or catch leaves early with return or a new error. You'll see this later in the lesson.

catch only works for errors thrown while the code runs. Some SyntaxErrors happen that way. For example, JSON.parse reads JSON text, and it throws a SyntaxError when the text is broken. A catch can deal with that.

A typing mistake in your own JavaScript file is different. Say you forget a closing brace, }. Then JavaScript can't read the file at all. No line runs, so the try never starts.

const cart = { total: 12 };

try {
  if (cart.total > 10) throw new Error("Limit reached");
  console.log("checkout");
} catch (error) {
  console.log("show message: " + error.message);
}

Line 1 makes a cart whose total is 12. On line 4, 12 is more than 10, so the if throws an error with the message Limit reached. Line 5 never runs. The catch block prints show message: Limit reached, and the page keeps working.

When JavaScript throws an error, the thrown value is usually an Error object. It has three properties you'll use most:

• name is the kind of error, like TypeError.
• message says what went wrong, in words.
• stack is text that shows where the error was made, and which function calls led there. Each browser writes it a little differently.

JavaScript has several built-in kinds of error. Read each row of the table as: this kind of error, what usually causes it, and a short example.

Try the playground below. Each button throws a real error in your browser and catches it straight away. Then you can see the properties your browser filled in.

1try {2  JSON.parse("{broken json}");3} catch (error) {4  console.log(error.name);5  console.log(error.message);6  console.log(error.stack?.split("\n")[0]);7  console.log(error instanceof Error);8  console.log(error.cause);9}

An error can also have a cause property. You add it yourself when you make a new error because of an older one. The new error gets a clearer message. cause keeps the older error, so the first reason isn't lost.

function readSettings() {
  throw new SyntaxError("bad JSON");
}

try {
  readSettings();
} catch (cause) {
  const error = new Error("Could not load settings", { cause });
  console.log(error.message);
  console.log(error.cause.name);
}

Line 2 throws a SyntaxError. Line 7 catches it in a variable called cause. Line 8 makes a new error with a clearer message. The { cause } part is short for { cause: cause }: it keeps the first error inside the new one. Line 9 prints Could not load settings, and line 10 prints SyntaxError.

try {
  throw "offline";
} catch (error) {
  console.log(typeof error);
  console.log(error);
}

Line 2 throws the text "offline". That is allowed, even though it isn't an Error object. Line 4 prints string, and line 5 prints offline. A string has no name or message, so check what you caught before you read them.

Optional catch binding

In catch (error), the name error is called the catch binding. It is the variable that holds the thrown value. Sometimes you don't need that value. You only need to know that something failed. Then you can leave the name out and write catch { ... }. This is called optional catch binding.

1try {2  JSON.parse(settingsText);3} catch {4  settings = defaultSettings;5}

Line 2 reads the settings text as JSON. If that throws, line 4 uses the default settings instead. Line 3 has no name in brackets, because every failure gets the same default.

Keep the name, catch (error), when you need the error. For example, when you want to:

• Print or log the error.
• Check error.name.
• Show a message that depends on the error.
• Throw the error again.

A catch block should only deal with errors it understands. Other errors should go on to code that can deal with them. To pass an error on, you throw it again from inside catch: throw error. This is called rethrowing.

1class ValidationError extends Error {}2 3function saveName(name) {4  try {5    validateName(name);6    return "Saved";7  } catch (error) {8    if (!(error instanceof ValidationError)) {9      throw error;10    }11    return "Please enter a name.";12  }13}

Line 1 makes a new kind of error, ValidationError, for bad form input. extends Error means it is a kind of Error. Line 5 calls validateName, a function that isn't shown here. It checks the name and may throw. Line 8 asks: is this error a ValidationError? If not, line 9 throws it again. Only a ValidationError reaches line 11, which returns a friendly message.

This lesson keeps ValidationError as small as possible. The next lesson, Throwing & custom errors, covers throw, making your own kinds of error, and cause in more depth.

finally runs just before JavaScript leaves the try statement. That happens in four cases:

• try finishes with no error.
• catch deals with an error.
• An error leaves, and no catch stops it.
• try or catch runs return.

There is one trap. If finally itself runs return or throw, that replaces what was already happening. The earlier return value or error is lost. Step through these three puzzles, and guess each result before you step.

1function returnFromTry() {2  try {3    return "try value";4  } finally {5    return "finally value";6  }7}8 9function throwThenFinallyThrows() {10  try {11    throw new TypeError("try failed");12  } finally {13    throw new RangeError("cleanup failed");14  }15}16 17function returnStillCleansUp() {18  const steps = [];19  try {20    steps.push("try");21    return steps.join(" → ");22  } finally {23    steps.push("finally");24    console.log(steps.join(" → "));25  }26}27 28console.log(returnFromTry());Run29try {30  throwThenFinallyThrows();31} catch (error) {32  console.log(error.name + ": " + error.message);33}34console.log(returnStillCleansUp());

function saveDraft() {
  try {
    return "saved";
  } finally {
    console.log("stop spinner");
  }
}

console.log(saveDraft());

Line 3 gets ready to return "saved". Before the value reaches the caller, finally runs, and line 5 prints stop spinner. A spinner is the turning icon a page shows while it waits. Then line 9 prints saved.

function chooseMessage() {
  try {
    return "saved";
  } finally {
    return "failed";
  }
}

console.log(chooseMessage());

Line 3 gets ready to return "saved". Then finally runs, and line 5 returns "failed" instead. The "saved" value is lost, so line 9 prints failed. This is a common mistake.

What try/catch cannot catch

A catch block only catches errors thrown while its try block is running. Two cases surprise people, because the error happens outside that time. Read each row of the table as: in this case, does this catch run, and why?

setTimeout(fn, 0) asks JavaScript to run the function fn later, after the current code finishes. A function you hand to other code, to run later, is called a callback.

try {
  setTimeout(() => {
    throw new Error("late error");
  }, 0);
} catch {
  console.log("outer catch");
}
console.log("try finished");

Line 2 only schedules the callback. It doesn't run it yet. So try finishes with no error, and line 8 prints try finished. Later, the callback runs, and line 3 throws. The outer catch is already finished, so nothing catches the error. The console shows it as an uncaught error: Error: late error.

If you wrote the callback yourself, put a try/catch inside it.

1try {2  setTimeout(() => {3    try {4      throw new Error("late");5    } catch (error) {6      console.log("callback caught itself");7    }8  }, 0);9} catch (error) {10  console.log("outer catch ran");11}12console.log("try finished");

Line 12 prints try finished first. Later, the callback runs. Its own try on line 3 is running when line 4 throws, so the catch on line 5 deals with it. Line 6 prints callback caught itself. A later lesson on promises and async/await shows more ways to handle errors in code that runs later.

async function loadProfile() {
  try {
    await Promise.reject(new Error("Profile unavailable"));
  } catch (error) {
    console.log(error.message);
  }
}

loadProfile();

await is different from a timer. A promise is a value that arrives later. Promise.reject(...) makes a promise that fails with an error. On line 3, await pauses the async function until the promise is done.

When the promise fails, the function goes on from line 3 and throws the error right there, inside try. So the catch on line 4 deals with it, and line 5 prints Profile unavailable. A callback that throws later still needs its own try/catch.

Where you will use this

Good try blocks are small. Put only the line that might fail inside try. Deal with the error you expect. Leave the rest of the function as normal code.

• Reading JSON: use a default value when the JSON text is broken, so a settings screen still opens.
• Checking input: show a friendly message when a user types something wrong. Throw any other error again.
• Cleaning up: use finally to reset the page after work that might fail. For example, stop a spinner.
• Finding bugs: when you can't fix an error where it happens, log its name, message, and stack.

function readSettings(text) {
  try {
    return JSON.parse(text);
  } catch {
    return { theme: "light" };
  }
}

console.log(readSettings("{broken}").theme);

The text {broken} is not valid JSON, so line 3 throws a SyntaxError. The catch on line 4 returns a light theme instead. Line 9 prints light, and the settings screen still works.

try {
  try {
    JSON.parse("{broken}");
  } catch {
    console.log("inner fallback");
    throw new Error("settings unavailable");
  }
} catch (error) {
  console.log("outer report: " + error.message);
}

A try can sit inside another try. Line 3 throws a SyntaxError. The inner catch on line 4 deals with it: line 5 prints inner fallback, and line 6 throws a new error with a clearer message. The outer catch on line 8 gets that new error, and line 9 prints outer report: settings unavailable.

Put one try inside another only when each one has a different job.

Common mistakes

Try each exercise on your own first. Use the hints only if you get stuck.

const events = [];
try {
  events.push("try");
  throw new TypeError("boom");
} catch (error) {
  events.push(error.name);
} finally {
  events.push("finally");
}
console.log(events.join(" > "));

function parseOrDefault(text, fallback) {
  try {
    return JSON.parse(text);
  } catch {
    return fallback;
  }
}
console.log(parseOrDefault("{\"count\":2}", { count: 0 }).count);
console.log(parseOrDefault("broken", { count: 0 }).count);

function parseOrDefault(text, fallback) {
  try {
    return JSON.parse(text);
  } catch {
    return fallback;
  }
}
console.log(parseOrDefault("{\"count\":2}", { count: 0 }).count);
console.log(parseOrDefault("broken", { count: 0 }).count);

function chooseName() {
  try {
    return "Ada";
  } finally {
    return "Grace";
  }
}

function chooseName() {
  try {
    return "Ada";
  } finally {
    console.log("cleanup");
  }
}
console.log(chooseName());

class ValidationError extends Error {}
function readAge(value) {
  try {
    const age = Number(value);
    if (Number.isNaN(age)) throw new ValidationError("Age must be a number");
    if (age < 0) throw new RangeError("Age cannot be negative");
    return "Age: " + age;
  } catch (error) {
    if (!(error instanceof ValidationError)) throw error;
    return "Use digits only.";
  }
}
console.log(readAge("ten"));

class ValidationError extends Error {}
function readAge(value) {
  try {
    const age = Number(value);
    if (Number.isNaN(age)) throw new ValidationError("Age must be a number");
    if (age < 0) throw new RangeError("Age cannot be negative");
    return "Age: " + age;
  } catch (error) {
    if (!(error instanceof ValidationError)) throw error;
    return "Use digits only.";
  }
}
console.log(readAge("ten"));

try {
  setTimeout(() => {
    try {
      throw new Error("late");
    } catch {
      console.log("callback caught itself");
    }
  }, 0);
} catch {
  console.log("outer catch");
}
console.log("try finished");

Pick an answer first. Then read the explanation, even when you were right.

Key takeaways

• try holds code that might fail. catch runs only if that code throws, and it gets the error.
• finally runs just before JavaScript leaves the try statement, even after a return or an error.
• An Error object usually has name, message, and stack. Some also have cause.
• Write catch { ... } with no name only when you never use the error.
• Throw again any error your catch can't deal with properly.
• try can't catch a typing mistake in the same file, or an error thrown later in a timer callback.

Up next: Throwing & custom errors.