Errors and exceptions

Review Workers errors and exceptions.

​​ Error pages generated by Workers

When a Worker running in production has an error that prevents it from returning a response, the client will receive an error page with an error code, defined as follows:

Other 11xx errors generally indicate a problem with the Workers runtime itself. Refer to the status page Open external link if you are experiencing an error.

​​ Loop limit

A Worker cannot call itself or another Worker more than 16 times. In order to prevent infinite loops between Workers, the CF-EW-Via header’s value is an integer that indicates how many invocations are left. Every time a Worker is invoked, the integer will decrement by 1. If the count reaches zero, a 1019 error is returned.

​​ Runtime errors

Runtime errors will occur within the runtime, do not throw up an error page, and are not visible to the end user. Runtime errors are detected by the user with logs.

​​ Identify errors: Workers Metrics

To review whether your application is experiencing any downtime or returning any errors:

1. Log in to the Cloudflare dashboard Open external link and select your account.
2. In Account Home, select Workers & Pages.
3. In Overview, select your Worker and review your Worker’s metrics.

​​ Debug exceptions

After you have identified your Workers application is returning exceptions, use wrangler tail to inspect and fix the exceptions.

Exceptions will show up under the exceptions field in the JSON returned by wrangler tail. After you have identified the exception that is causing errors, redeploy your code with a fix, and continue tailing the logs to confirm that it is fixed.

​​ Set up a logging service

A Worker can make HTTP requests to any HTTP service on the public Internet. You can use a service like Sentry Open external link to collect error logs from your Worker, by making an HTTP request to the service to report the error. Refer to your service’s API documentation for details on what kind of request to make.

When using an external logging strategy, remember that outstanding asynchronous tasks are canceled as soon as a Worker finishes sending its main response body to the client. To ensure that a logging subrequest completes, pass the request promise to event.waitUntil() Open external link . For example:

export default {
  async fetch(request, env, ctx) {
    function postLog(data) {
      return fetch("https://log-service.example.com/", {
        method: "POST",
        body: data,
      });
    }

    // Without ctx.waitUntil(), the `postLog` function may or may not complete.
    ctx.waitUntil(postLog(stack));
    return fetch(request);
  }
}

addEventListener("fetch", (event) => {
  event.respondWith(handleEvent(event));
});

async function handleEvent(event) {
  // ...

  // Without event.waitUntil(), the `postLog` function may or may not complete.
  event.waitUntil(postLog(stack));
  return fetch(event.request);
}

function postLog(data) {
  return fetch("https://log-service.example.com/", {
    method: "POST",
    body: data,
  });
}

​​ Go to origin on error

By using event.passThroughOnException, a Workers application will forward requests to your origin if an exception is thrown during the Worker’s execution. This allows you to add logging, tracking, or other features with Workers, without degrading your application’s functionality.

export default {
  async fetch(request, env, ctx) {
    ctx.passThroughOnException();
    // an error here will return the origin response, as if the Worker wasn't present
    return fetch(request);
  }
}

addEventListener("fetch", (event) => {
  event.passThroughOnException();
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  // An error here will return the origin response, as if the Worker wasn’t present.
  // ...
  return fetch(request);
}

​​ Related resources

• Log from Workers - Learn how to log your Workers.
• Logpush - Learn how to push Workers Trace Event Logs to supported destinations.