How to Fix "Uncaught (in promise)" Errors in JavaScript

Uncaught (in promise) TypeError: ... is one of the most disorienting lines in the console, because the stack trace rarely points at the code you actually wrote. It points into the promise machinery, or into a line that looks completely fine, while the real bug is somewhere upstream — an await that never got a try/catch, a .then() chain missing its final .catch(), or an async function that fired and was never watched. This guide walks through what the error means, the handful of patterns that cause it, and the fixes that make rejections predictable instead of terrifying.

This is different from a synchronous throw. A synchronous error unwinds the call stack immediately and, if nothing catches it, crashes right where it happened. A promise rejection is asynchronous: the engine has to wait a full microtask turn to see whether anything eventually attaches a handler before deciding the rejection is truly unhandled. Per MDN, the browser's unhandledrejection event fires precisely when a rejection reaches the end of that microtask turn with no handler attached. That delay is exactly why the error in the console so often looks disconnected from its cause — by the time it surfaces, the code that triggered it has already finished running.

Almost every unhandled rejection traces back to one of these five shapes.

Two more shapes worth naming because they are easy to write by accident:

• An await that isn't actually inside the try: a stray line after the closing brace, or an await inside a callback that the outer try/catch doesn't cover, defeats the whole point of the wrapper.
• An async function whose caller doesn't await or catch it: marking a function async turns every throw inside it into a rejected promise. If the caller treats it like a synchronous function and never awaits or attaches a handler, that rejection has nowhere to go.

The same five root causes map to a small set of fixes. The right-hand column is worth internalising: a linter can catch some of these mechanically, but the two most dangerous ones — a mishandled HTTP status and an await that sits outside its try — are perfectly valid code that no rule will flag for you.

Every fix comes down to making sure exactly one place is responsible for a promise's rejection. Wrap an await in try/catch when you can react to the failure right there — retry, show an error state, fall back to a default. End every .then() chain with a final .catch(), even if you think nothing can fail; APIs change, and a chain without one is a rejection waiting to happen the day it does. For a promise you deliberately don't want to await — logging an analytics event, warming a cache — attach .catch() and prefix the call with void so it reads as an intentional fire-and-forget rather than a forgotten await.

A rejection is a rejection no matter which syntax created it, but the two styles put the handler in different places, and mixing them is where people slip. With async/await, a rejected promise behaves like a thrown exception at the await point, so a surrounding try/catch catches it — the same construct you'd use for synchronous errors. With .then() chains, there is no exception to catch synchronously; you attach a rejection handler either as the second argument to .then(onFulfilled, onRejected) or, better, as a trailing .catch() that also covers throws inside the earlier .then() callbacks.

Even in a well-handled codebase, something will eventually slip through — a third-party library's internal promise, a rare timing edge case, a rejection from code you don't control. The unhandledrejection event on window (and the equivalent on WorkerGlobalScope inside Web Workers) fires whenever a rejection reaches the end of a microtask turn with no handler attached. The event is cancelable: its event.reason holds whatever the promise rejected with, event.promise is the promise object itself, and calling event.preventDefault() stops the browser's default console logging. MDN also documents a companion rejectionhandled event that fires if a handler is attached later, after the rejection was already reported.

On the server the stakes are higher. Node.js exposes the same failure through the 'unhandledRejection' process event, which is emitted whenever a promise is rejected and no handler is attached within a turn of the event loop; the listener receives the reason and the rejected promise. What changed in Node.js 15 is the default consequence: as of PR #33021, the default --unhandled-rejections mode became throw, meaning an unhandled rejection is re-raised as an uncaught exception and terminates the process with a non-zero exit code. Before v15 it merely printed an UnhandledPromiseRejectionWarning.

The --unhandled-rejections=mode flag lets you choose the behavior: throw (default — emit the event, then throw as uncaught if unhandled), strict (always throw, even with a listener attached), warn (warn but keep running), warn-with-error-code (warn and set a non-zero exit code without crashing), and none (silence it entirely). Don't reach for warn or none to make the message go away — a rejection you ignore on a request handler is a bug you'll pay for later. Keep a process.on('unhandledRejection', ...) listener for structured logging, then fix the missing .catch() upstream.

When the console line doesn't tell you which promise rejected, DevTools can. In the Sources panel, the Pause on exceptions breakpoint stops execution the moment an exception is thrown — tick "Pause on caught exceptions" too and the debugger will halt inside the rejecting async function, at the real throw, before the rejection has floated up into the opaque "(in promise)" report. To follow the trail across the await boundary, enable the Async call stack checkbox next to the Call Stack pane; DevTools then stitches the pre-await frames onto the current stack for promises, timers, XMLHttpRequest, and event listeners, so you can see the click handler that kicked off the request that eventually rejected.

If you're in React and expecting an error boundary to catch a rejected fetch inside a click handler or a useEffect, it won't. The React docs are explicit that error boundaries do not catch errors in event handlers or asynchronous code — they only catch what throws during rendering, in lifecycle methods, and in constructors. A promise rejection in an event handler runs outside the render cycle entirely, so it sails past the boundary and lands in the console as "Uncaught (in promise)." The fix is the same one this whole guide is about: a try/catch around the await in the handler, or a .catch() on the chain, and a state update to show the error UI yourself. (Newer patterns like the use hook, which unwrap a promise during render, do surface to a boundary — but a fetch fired from a handler never will.)

Unhandled rejections are notoriously slippery in testing for two reasons. First, the crash often surfaces disconnected from its cause: a click handler kicks off an async save, the handler itself returns immediately and looks fine, and the rejection appears in the console moments later with a stack trace that no longer matches what the user was doing. Second, an unhandled rejection frequently doesn't crash the page at all — the UI keeps rendering, the click still "worked" from the user's point of view, and the only evidence is a red line in a console nobody was watching. That combination means these errors pile up quietly in production long before anyone notices a pattern.

A few honest limits are worth stating. A global unhandledrejection or process.on('unhandledRejection') listener is a reporting backstop, not a control-flow mechanism — you cannot retry a request or recover state from it, because by the time it fires the rejection is already loose and you often can't tell which call site produced it. Silencing rejections with event.preventDefault() or Node's --unhandled-rejections=none hides real bugs and should be reserved, if ever, for a rejection you have positively identified and decided is benign. Promise.allSettled is the right tool only when partial failure is genuinely acceptable; if any one result is required, Promise.all with a proper .catch() is more honest. And catching a rejection is not the same as handling it — an empty catch {} that swallows the error is arguably worse than the original warning, because now the failure is both broken and invisible. The goal throughout is one owner per promise, and a real decision at that owner about what failure means.