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.

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.

1. Watch the live failure:

wrangler tail

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

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

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

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