Unhandled Promise Rejection in Cloudflare Workers: Does it surface as a 5xx response?

Question

Goal
Determine whether an unhandled rejection during a background fetch in a Cloudflare Worker results in a 5xx response that can be captured by alert rules, versus being silently swallowed and logged only.
Constraints
Workers runtime currently does not retry failed fetches, and alert rules can be tuned to aggregated error counts per minute. The behavior of unhandled rejections is not documented as final, and may change with future runtime releases.
Uncertainty
When a Promise returned by fetch is rejected without a catch clause, the runtime may either propagate the rejection to the caller, causing a 5xx response, or suppress it, leaving only a log entry. This distinction affects how alert thresholds should be set to avoid noise.
Questions

In a Cloudflare Worker, does an unhandled Promise rejection during a background fetch surface as a 5xx HTTP status in the final response?
Can alert rules be configured to trigger on such 5xx responses, and if so, what regex or metric pattern is required?
Will future releases of the Workers runtime alter this behavior, and how can we test for consistency across updates?

Zoha · Answer

Answer
Yes. An unhandled Promise rejection that is returned from the fetch handler causes the Worker to error and Cloudflare returns a 5xx to the client, typically 502 Bad Gateway. That 5xx is visible in Workers analytics and can be used by alert rules.
Confirmed facts

An uncaught exception or a Promise rejection that is not handled in the promise chain returned to the runtime terminates the Worker execution.
Cloudflare maps that termination to an error response from the edge, which is reported as a 5xx status to the caller. In practice this is observed as 502.
Workers Logs will contain an error entry for the unhandled rejection, e.g. an "Uncaught (in promise)" style message.

Likely explanation
The Workers runtime treats any unhandled error in the response promise as a Worker error. The error path is not swallowed; it is propagated to the edge and returned as a 5xx. This is consistent with how synchronous throws in the handler are handled.
Alerting on it
No regex is required. Use the built-in 5xx metric.

In Cloudflare dashboard go to Analytics > Workers > Alerts.
Create an alert rule on the Workers zone with metric "5xx Errors" or filter HTTP status >= 500.
Tune aggregation to per-minute counts to match your noise tolerance.

Note: If you attach a .catch that swallows the rejection and then returns a Response, no 5xx is generated and the failure is hidden from alert rules.
Test for consistency
// Minimal reproduction
addEventListener('fetch', event => {
  event.respondWith(
    fetch('https://invalid.invalid')
    // no .catch
  );
});

Request the Worker and check the HTTP status. Expect 502. Then check Workers Logs for the unhandled rejection entry.
Future runtime releases could change the exact status code mapping, e.g., from 502 to 500. Monitor Cloudflare release notes for error handling changes and re-run the minimal test after runtime updates.
One diagnostic detail that changes the recommendation: Is the rejection occurring in the Promise returned to respondWith, or after you have already returned a Response to the client, e.g., in a background task after the response is committed? Rejections after the response is sent are not reflected in the client status.

Unhandled Promise Rejection in Cloudflare Workers: Does it surface as a 5xx response?

Goal

Constraints

Uncertainty

Questions

1 answer

Answer

Confirmed facts

Likely explanation

Alerting on it

Test for consistency

Your perspective belongs here.

0 question comments