Catching Errors in Async Code

Inside an async function you use the ordinary try and catch, but you have to await the call inside the try block. A rejected promise only throws when you await it, so a try block that calls the function without awaiting will not catch anything.

async function risky() {
  throw new Error("boom");
}

// A promise chain handles the rejection explicitly.
risky()
  .then(() => console.log("not reached"))
  .catch((err) => console.log("caught in the chain:", err.message));

// try and catch works when you await the call.
(async () => {
  try {
    await risky();
  } catch (err) {
    console.log("caught with await:", err.message);
  }
})();

There is a subtlety in that snippet that is worth spelling out. The first call is not awaited, but it is not a leak either, because the catch handler is attached to the chain in the same tick. The rule is not that every call must be awaited. The rule is that every promise must end up with a rejection handler somewhere, and the two ways to do that are to await it inside a try block or to attach a catch handler.

For code that mixes several operations, the try and catch around a block of awaits is usually the clearest form. If you want to run a step and ignore its failure without stopping the rest, wrap that step individually so the error is handled where it happens.

One more pattern worth knowing is the finally method, which runs its callback whatever happened. It is the right place for cleanup such as hiding a loading spinner, and it does not swallow the error, because it runs before the rejection continues up the chain.

An unhandled rejection is a promise that rejects and never gets a rejection handler. It usually happens by accident: a call returns a promise, the caller forgets to return it or to await it, and the failure has nowhere to go.

In a browser the runtime reports it. The console shows an unhandled rejection error, and the error is also delivered to the global error event, which is how error monitoring tools pick it up. The page keeps running, so the failure is easy to miss unless someone is watching the console.

In Node the behaviour is stricter. Since version fifteen, an unhandled rejection terminates the process by default with a non-zero exit code, on the grounds that a silent failure in a server is worse than a crash. You can change that behaviour, and you can register a process level handler for the unhandledRejection event, but the safer practice is to fix the code that is missing the handler.

How to prevent them. Return every promise from the function that starts it, so the caller can handle it. Await inside a try block when you need to recover. Attach a catch handler to anything you fire and forget. And when you deliberately ignore a failure, say so explicitly with a catch that logs rather than with a bare call.

One warning about a common wrong fix. Adding a catch handler that only logs still leaves the outer promise in a fulfilled state, so a caller that was relying on the rejection will never learn about the failure. If the failure matters, rethrow it after logging.