Guide

Error handling

Suggest Edits

Programming errors, unexpected input from end-users, changes in documents returned from htmlRequest(), and timeouts can cause an EdgeWorkers function to fail. By default, when an EdgeWorkers function fails the response is halted and information about the failed request is generated. As an alternative, when a failure occurs you can:

About error messages

When an EdgeWorkers execution error occurs, the request is halted unless you configure one of the other available options. The response generates details about the failed request that you can use to troubleshoot. To view these messages you need to enable Enhanced debug headers. There are several different types of errors that produce information including:

  • Uncaught exceptions - Unhandled JavaScript errors
  • CPU timeout - Exceeding the CPU time limit for your resource tier
  • Wall timeout - Exceeding the wall clock time limit for your resource tier
  • Memory limit - Exceeding the memory allocation for your resource tier
  • HTTP sub-request failures - Sub-request timeouts or errors
  • Initialization failures - Errors during module initialization

EdgeWorkers failures caused by a coding issue throw a JavaScript error. Where possible, catch errors in your JavaScript code and execute alternative logic.

To learn more, go to About JavaScript troubleshooting.

Continue on Error

The Continue on error behavior applies to all event handlers except for responseProvider. It lets a request proceed even when an EdgeWorkers event handler fails. You should consider using this option for use cases where EdgeWorkers provides enhancement features that are not critical to the request, such as A/B testing, Analytics, and Personalization.

When Continue on Error is enabled in the EdgeWorkers behavior:

  • Failed event handlers don't stop the request.
  • Subsequent event handlers still execute.
  • The request continues through Property Manager as if the failed EdgeWorkers function hadn't run.
  • Errors are logged for later investigation.

Continue on Error is supported for onClientRequest, onClientResponse, onOriginRequest, onOriginResponse.

responseProvider does not support Continue on error.

👍

Go to Enable Continue on error to learn more.

Detect errors in Property Manager

You can also detect EdgeWorkers errors during the request and respond with an alternate action. To do this you need to configure a Property Manager rule to detect the error and customize the response to the error.

Use the EdgeWorkers Execution Status match condition to detect failures of events other than responseProvider. In most cases, you'll want to check the status in the client-response metadata stage to ensure the status is checked after all events have executed.

👍

This condition will match errors that occur regardless of the setting used for Continue on Error.

Errors in ResponseProvider

Use the built-in variable AK_EDGEWORKERS_RP_STATUS to detect errors in responseProvider. Check that the value of AK_EDGEWORKERS_RP_STATUS is not empty and does not match any of:

  • *success*
  • *unimplementedHandler*
  • *unknownEdgeWorker* (optional, if you want to treat a deactivated EdgeWorker ID as a success)

To match against these values, first store the value in a PMUSER variable that lets you match on the contents of the variable, then match against the PMUSER variable in a following rule.

📘

Go to the Variables overview in the Property Manager guide to learn more.

Site Failover

After detecting an EdgeWorkers error, you can take custom actions such as retrying the request or initiating a failover to alternate content. The Site Failover Property Manager behavior lets you define what logic to execute in the event that an EdgeWorkers function fails.

You can intercept these errors and any others by using one of these supported failover actions:

  • Redirect to a different location by specifying a redirect action. This action sends the end user to alternate content with an end user facing Location change - this is best suited for full HTML page requests.

  • Use an alternate origin and path so the end user remains on the original URL.

  • Display a 500 error to the end user.

  • Use EdgeWorkers Execution Status in a match condition.

  • Retry the failed EdgeWorkers request and continue processing the delivery property metadata.

  • By-pass the failed EdgeWorkers function and serve the same URL. Support is required to implement this Failover action. Contact your account team or send an email to edgeworkers@akamai.com for more information.

🚧

Site Failover and Continue on error

If you are using Continue on error, you should not use Site Failover for EdgeWorkers error handling. Site Failover, however, can still be used to handle errors from the origin.

When Continue on error is enabled, a failed EdgeWorkers request will not stop the main request from continuing. This lets you investigate the reason for an EdgeWorkers failure at a later date and let the main request continue.

📘

When testing Site Failover you need to remove the akamai-x-ew-debug-rp Pragma header. For more information refer to the known issue.

👍

Go to Configure Site Failover to learn more.

Updated about 6 hours ago