workerd uncaught exception: unhandled promise rejection in fetch handler

TL;DR

Somewhere in your fetch handler a promise is floating with no await and no catch, and when it rejects, workerd reports it as an uncaught exception. Find every promise the handler creates (fetch calls, KV reads, D1 queries), await each one or attach error handling, and move genuine fire-and-forget work into ctx.waitUntil so it has a proper home.

Uncaught (in promise) Error: [rejection reason]

Steps

1. Get the rejection with its stack:

wrangler tail

Expected: log lines showing the uncaught rejection and a stack pointing at the call that created the promise.

1. Audit the handler for floating promises. Search for async calls whose results are never awaited or returned:

grep -rn "fetch(\|\.put(\|\.get(" src | grep -v await

Expected: a short list of suspects; every real async call in the hot path should be awaited.

1. Await or handle each one. The pattern that fixes most cases:

async function handler(request, env, ctx) {
  try {
    const data = await env.MY_KV.get("key");
    const res = await fetch("https://example.com/api");
    return new Response(data);
  } catch (err) {
    console.log("handler failed", err);
    return new Response("upstream error", { status: 502 });
  }
}

Expected: no promise in the request path is left un-awaited.

1. Move true background work (analytics pings, cache writes) into waitUntil so it runs after the response without floating:

ctx.waitUntil(env.MY_KV.put("last-visit", Date.now().toString()));

Expected: background tasks still run, but their failures no longer surface as unhandled rejections in the request path.

1. Redeploy and watch the tail log on the previously failing route.

Expected: the uncaught rejection is gone.

Use this when

• Workerd logs "Uncaught (in promise)" from the fetch handler
• A route fails intermittently with no synchronous stack trace
• The error appeared after adding a new async call to the handler

Not for this skill when

• The throw is synchronous with a normal stack; that is a regular code bug
• The rejection comes from a scheduled handler or queue consumer, not fetch
• The promise rejects inside waitUntil; that is logged but does not fail the response

Variant phrasings

• workerd unhandled promise rejection fetch handler
• Uncaught (in promise) cloudflare worker
• cloudflare worker promise rejection no await

Why it happens

Workerd treats an unhandled rejection as a bug loud enough to report, because a silently failed write or fetch is worse than a noisy one. The fetch handler returning does not settle promises it left behind, so a KV write or API call that rejects after the response went out still counts as unhandled.

Edge cases

• Rejections inside ctx.waitUntil are still logged as errors; attach a catch there too if the background task can fail.
• Promise.all rejects on the first failure and can orphan the rest; use allSettled when partial failure is acceptable.
• Library internals sometimes create promises you never see; if the stack points into a dependency, wrap the library call in try/catch.
• Adding await changes timing; a handler that relied on fire-and-forget parallelism may need restructuring, not just await sprinkled on.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jdkoFVCtzFiRNaV74qk6AQ