workerd uncaught exception: fetch handler did not return a Response

Not specified by the original author.

TL;DR

The fetch handler must return a Response (or a promise of one) on every path. A missing return in a branch, an async function that falls off the end, or returning a plain object instead of a Response crashes the request with an uncaught exception. Audit every branch for a return, wrap the handler so unexpected values become 500s, and the crash disappears.

The query

workerd uncaught exception: fetch handler did not return a Response

Use this when

• The worker crashes on some requests but not others.
• The failing paths involve early returns, conditionals, or try/catch.
• The handler sometimes returns undefined according to type checks.

Not for

• 'Response constructor: invalid redirect value' (constructor misuse, separate fix).
• Unhandled promise rejections elsewhere in the code.
• Wrong status codes or bodies (logic bug, not a crash).

Steps

Step 1: Find the path that returns nothing

Reproduce with the failing request and read the stack: it points at the handler's exit.

Expected result: one branch (an if without else, a catch that logs and falls through, a guard clause) has no return.

Step 2: Make every branch return a Response

export default {
  async fetch(request, env) {
    try {
      if (request.method !== "GET") {
        return new Response("method not allowed", { status: 405 });
      }
      return await handleGet(request, env);
    } catch (e) {
      console.error(e);
      return new Response("internal error", { status: 500 });
    }
  },
};

Expected result: no path falls through. The catch converts crashes into 500s.

Step 3: Wrap helpers that build responses

If handleGet can return undefined, the bug moved, not vanished. Assert at the boundary or default it.

Expected result: helper contracts are explicit: they return Response, always.

Step 4: Add a type check in CI

Type the handler as returning a promise of a Response and let the compiler flag undefined returns.

Expected result: the class of bug is caught at build time instead of in production.

Step 5: Redeploy and exercise the failing path

Expected result: the previously crashing request returns a proper Response. Watch tail for the uncaught exception disappearing.

Why it happens

JavaScript happily returns undefined from functions that fall off the end, and async handlers make the missing return invisible until runtime. The Workers runtime is strict: the contract is Response-or-crash. Conditional logic added over time creates the untested branch that finds the hole.

Edge cases

• Returning a plain object is also a failure. It must be a Response instance.
• Middleware chains that forget to return the next handler produce this crash one layer removed from the bug.
• Scheduled and queue handlers have their own contracts; this error is specific to fetch.
• Awaiting a promise that resolves to undefined counts as returning undefined. Check what the awaited value is.

Provenance

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

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

Thread query: workerd uncaught exception: fetch handler did not return a Response

TL;DR: The fetch handler must return a Response (or a promise of one) on every path. A missing return in a branch, an async function that falls off the end, or returning a plain object instead of a Response crashes the request with an uncaught exception. Audit every branch for a return, wrap the handler so unexpected values become 500s, and the crash disappears.

Not specified by the original author.

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.

2. 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.

3. 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.

4. 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.

5. 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

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

Thread query: 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.

Not specified by the original author.

TL;DR

"TypeError: fetch failed" is workerd's generic way of saying the network call blew up, and it hides the real reason. Wrap the fetch in try/catch, log the exact URL that failed, then work through the usual suspects: DNS, TLS, timeouts, and whether the target is actually reachable from the public internet.

Uncaught TypeError: fetch failed

Steps

1. Catch it and get the details. Wrap the outbound fetch in try/catch and log the URL plus the error cause:

try {
  const res = await fetch(url, { signal: AbortSignal.timeout(10000) });
  return res;
} catch (err) {
  console.log("fetch failed for", url, err.cause || err);
  throw err;
}

Expected: the tail log now shows which URL failed and a cause hint instead of a bare TypeError.

2. Watch the live failure:

wrangler tail

Expected: log lines naming the failing URL each time the error reproduces.

3. Test the endpoint from outside the worker with any HTTP client and check the basics: DNS resolves, the TLS certificate is valid and not expired, and the server answers in a reasonable time.

Expected: you find the layer that fails (DNS, TLS handshake, or hung server) independent of the worker.

4. Check the two workerd-specific traps: the request must go to a publicly reachable address (private network addresses are not reachable from the edge), and the fetch must not reuse an already-consumed request body.

Expected: the URL is public and each fetch builds its own request object.

5. Redeploy and confirm the tail log is clean on the previously failing path.

Expected: no more uncaught fetch failures.

Use this when

• A worker throws uncaught "TypeError: fetch failed"
• An outbound API call works from your laptop but fails from the worker
• The error gives no URL or reason in the log

Not for this skill when

• The error names the subrequest limit or the CPU time limit; those are quota errors, not network failures
• The fetch succeeds but returns an unexpected status; that is an API problem
• The failure is on an inbound request to the worker, not an outbound fetch

Variant phrasings

• fetch failed cloudflare worker TypeError
• workerd uncaught exception fetch failed
• cloudflare worker outbound request fails with TypeError

Why it happens

Workerd runs fetches through its own network stack and collapses every failure mode (DNS miss, TLS error, refused connection, timeout, unreachable host) into one TypeError. Without a try/catch that logs the URL and cause, you are debugging blind, because the default uncaught message carries none of the context.

Edge cases

• Self-signed or expired certificates on the origin fail the TLS check; the fix is on the origin, not in the worker.
• An AbortSignal timeout that is too aggressive looks exactly like a server failure; give slow origins a realistic budget.
• Retries without backoff can turn one slow origin into a subrequest-limit error on top of the fetch failure.
• IPv6-only origins and origins behind aggressive bot protection fail in ways that look like generic network errors; test from a neutral network.

Provenance

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

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

Thread query: workerd uncaught exception: TypeError fetch failed

TL;DR: "TypeError: fetch failed" is workerd's generic way of saying the network call blew up, and it hides the real reason. Wrap the fetch in try/catch, log the exact URL that failed, then work through the usual suspects: DNS, TLS, timeouts, and whether the target is actually reachable from the public internet.