Fastly-generated errors

When errors happen during the processing of a request, Fastly may generate a synthetic HTTP response and these may be delivered to the end user, often with a 503 (service unavailable) status code.

This page describes the possible conditions that produce this outcome and how to handle such errors at the edge.

WARNING: Purging cache in response to unexplained elevated error rates may make things worse. Purges typically increase traffic to origin, which may exacerbate a problem rather than fixing it. Try to determine the cause of errors and be certain purging is the right solution.

Sources of errors

Often you'll become aware of errors in your Fastly service because undesirable HTTP responses (with HTTP status codes of 400 or higher) are being delivered to end users and reported to you.

But this doesn't necessarily mean something is wrong with your Fastly service. HTTP error responses may have a variety of possible causes:

  1. Your origin server served it. A well formed, valid HTTP response from your origin server is not considered an error by Fastly (and will not invoke vcl_error in VCL services), though it may itself represent an error that has occurred in your origin server. Unless you configure your service to handle such responses, they will be delivered to end users, and potentially cached.
  2. An explicit error statement in your VCL was executed. The error statement can be used in most VCL subroutines to immediately stop the normal VCL workflow, construct a synthetic response object, and transfer control to the vcl_error subroutine.
  3. You constructed an error response in a Compute application. Every Compute SDK provides the ability to construct responses from scratch, and you may have a code path that generates an error response.
  4. Something happened that caused Fastly to throw an error. These errors are created by Fastly and surfaced in various ways - both in VCL and Compute services. This page describes the possible errors of this type, how they are triggered and how to resolve them.

Fastly-generated errors

These are errors that are generated by Fastly which will halt your program and produce output to the client. Often they will emit output to STDERR too.

End user viewable error policy

Fastly believes that you own the relationship with your customers, and content that end users receive from your website should not be obviously delivered by Fastly. In general, users are not familiar with the role of edge networks, and should not need to be. Therefore, where errors occur and a response must be sent to the client, but your service is not able to produce one itself, Fastly will send a response that is either empty or unbranded.

Routing errors

Fastly may respond to some requests directly from our routing systems, without invoking your service. This often happens when the request is presented on a port that we do not support, or is syntactically invalid. In such cases our response is either to drop the connection or to issue a standards-compliant HTTP error response. The following list itemizes notable responses that may be generated at this layer.

HTTP StatusReason textDescription
414URI too longThe length of the URL exceeds our platform limits. On Compute services, this may create a 400 instead.
421Misdirected RequestIndicates a mismatch between the hostname provided in the TLS handshake (e.g., in the SAN entries in the TLS certificate) and the requested hostname in the HTTP Host header. This may happen if you are attempting to do domain fronting which is not supported by Fastly by default. Consider setting a host header override on the backend.
503Loop detectedThe request appears to originate from the same Fastly service that it is trying to invoke, or the request has transited too many Fastly servers. See loop detection.

Fastly-generated routing errors may occur when an end user request is presented to a Fastly POP, but also when requests are forwarded from one Fastly service to another (see service chaining) or from one Fastly POP to another (see shielding).

Error responses from our routing systems will either have an empty response body or will cite error 54113, a reference to Fastly's Autonomous System number.

NOTE: Error 54113 supersedes the obscure guru mediation error which we used for many years.

If you see error responses from your Fastly hosted domain and believe these errors are being generated before your code is invoked, contact Fastly support for assistance.

Errors in VCL services

VCL services can generate a number of specific errors that can be handled within VCL code. See Synthetic 503 errors in VCL for details.

Errors in Compute services

Unhandled errors, panics or exceptions in Compute programs usually produce descriptive output on stderr, and if the program terminates before generating a response, will cause a blank HTTP 500 (internal server error) to be served to the client.

stderr output can be captured using log tailing.

The kinds of output produced when programs terminate prematurely is affected by which compiler is used to construct the Compute program (which in practical terms means which language the program is written in). For example, Rust based Compute programs generate panics when they halt abruptly, while JavaScript applications will report unhandled promises, errors, and exceptions.

Platform errors triggered by the Compute platform

In addition to runtime panics and errors in the WebAssembly program, which report their own error states, it's possible for Compute programs to trigger platform errors by invoking Fastly's system interfaces and APIs in unexpected or illegal ways. In such cases the app will produce output on stderr such as "Fastly Error {number}".

If you encounter persistent errors of this kind, please contact Fastly support.

Loop detection

We automatically detect situations where your Fastly service appears to be forwarding requests endlessly to itself. When a loop is detected, Fastly blocks the request at the routing stage and generates a 503 error with a Loop detected reason text. Loops often occur when the same hostname is configured as both the domain and the backend for the same service, and the DNS for the domain resolves to Fastly.

To avoid creating a loop, ensure that traffic from Fastly to your origin server does not inadvertently go back to Fastly. Commonly this is done in one of these ways:

  • Use a separate hostname (e.g. pointing to your origin server, and configure that as the address of the backend in your Fastly service configuration.
  • Use an IP address instead of a hostname for your backend's address within your Fastly service's configuration. This allows your origin server to be configured with the same domain as your Fastly service.

Loop detection can also be triggered if the backend for one Fastly service is another Fastly service. Doing this intentionally is called service chaining, but it may also happen unintentionally if your service uses a backend operated by a third party that happens to also be a Fastly customer.

A request will be rejected as a loop if it exceeds one of these limits:

  • at most 3 prior visits to this POP on behalf of this Fastly service
  • at most 6 prior unique Fastly services executed by the request
  • at most 20 total prior hops, where a hop is defined as a handoff from one Fastly service to another

Although loop detected errors are triggered before your service code is invoked, the response will be returned to the parent instance of your service code, where it can be handled in VCL services by reading bresp.status and beresp.response in vcl_fetch or in a Compute program by examining the status and reason text exposed by the Response object.