Serving stale content

Last updated August 21, 2017

Fastly can optionally serve stale content when there is a problem with your origin server, or if new content is taking a long time to fetch from your origin server. For example, if Fastly can't contact your origin server, our POPs will continue to serve cached content when users request it. These features are not enabled by default.

Serving old content while fetching new content

Certain pieces of content can take a long time to generate. Once the content is cached it will be served quickly, but the first user to try and access it will pay a penalty.

This is unavoidable if the cache is completely cold, but if this is happening when the object is in cache and its TTL is expired, then Fastly can be configured to show the stale content while the new content is fetched in the background.

Usage

To activate this behavior simply add a stale-while-revalidate or stale-if-error statement to either the Cache-Control or Surrogate-Control headers in the response from your origin server. For example:

Cache-Control: max-age=600, stale-while-revalidate=30

will cache some content for 10 minutes and, at the end of that 10 minutes, will serve stale content for up to 30 seconds while new content is being fetched.

Similarly, this statement:

Surrogate-Control: max-age=3600, stale-if-error=86400

instructs the cache to update the content every hour (3600 seconds) but if the origin is down then show stale content for a day (86400 seconds).

Alternatively, these behaviors can be controlled from within VCL by setting the following variables in vcl_fetch:

set beresp.stale_while_revalidate = 30s;

set beresp.stale_if_error = 86400s;

Interaction with grace

Stale-if-error works exactly the same as Varnish's grace variable such that these two statements are equivalent:

set beresp.grace = 86400s;

set beresp.stale_if_error = 86400s;

However, if a grace statement is present in VCL it will override any stale-while-revalidate or stale-if-error statements in any Cache-Control or Surrogate-Control response headers.

Setting beresp.stale_if_error either via header or via VCL does nothing on its own. In order to serve stale, follow the instructions below.

Serving stale content on errors

In certain situations where your origin server becomes unavailable, you may want to serve stale content. These instructions provide an advanced configuration that allows all three possible origin failure cases to be handled using VCL. These instructions require the ability to upload custom VCL.

If Varnish cannot contact the origin for any reason, a 503 error will be generated.

The origin returns a valid HTTP response, but that response is not one we wish to serve to users (for instance, a 503).

The custom VCL shown below handles all three cases. If the origin is unhealthy, the default serve stale behavior is triggered by stale-if-error. In between the origin failing and being marked unhealthy, Varnish would normally return 503s. The custom VCL allows us to instead either serve stale if we have a stale copy, or to return a synthetic error page. The error page can be customized. The third case is handled by intercepting all 5XX errors in vcl_fetch and either serving stale or serving the synthetic error page.

WARNING: Do not purge all cached content if you are seeing 503 errors. Purge all overrides stale-if-error and increases the requests to your origin server, which could result in additional 503 errors.

Although not strictly necessary, health checks should be enabled in conjunction with this VCL. Without health checks enabled, all of the functionality will still work, but serving stale or synthetic responses will take much longer while waiting for an origin to timeout. With health checks enabled, this problem is averted by the origin being marked as unhealthy.

The custom VCL shown below includes the Fastly standard boilerplate. Before uploading this to your service, be sure to customize or remove the following values to suit your specific needs:

if (beresp.status >= 500 && beresp.status < 600) should be changed to include any HTTP response codes you wish to serve stale/synthetic for.

set beresp.stale_if_error = 86400s; controls how long content will be eligible to be served stale and should be set to a meaningful amount for your configuration. If you're sending stale_if_error in Surrogate-Control or Cache-Control from origin, remove this entire line.

set beresp.stale_while_revalidate = 60s; controls how long the stale_while_revalidate feature will be enabled for an object and should be set to a meaningful amount for your configuration. This feature causes Varnish to serve stale on a cache miss and fetch the newest version of the object from origin in the background. This can result in large performance gains on objects with short TTLs, and in general on any cache miss. Note that stale_while_revalidate overrides stale_if_error. That is, as long as the object is eligible to be served stale while revalidating, stale_if_error will have no effect. If you're sending stale_while_revalidate in Surrogate-Control or Cache-Control from origin, remove this entire line.

synthetic {"<!DOCTYPE html>Your HTML!</html>"}; is the synthetic response Varnish will return if no stale version of an object is available and should be set appropriately for your configuration. You can embed your HTML, CSS, or JS here. Use caution when referencing external CSS and JS documents. If your origin is offline they may be unavailable as well.

sub vcl_recv{if(req.http.Fastly-FF){setreq.max_stale_while_revalidate=0s;}#FASTLY recvif(req.request!="HEAD"&&req.request!="GET"&&req.request!="FASTLYPURGE"){return(pass);}return(lookup);}sub vcl_fetch{/* handle 5XX (or any other unwanted status code) */if(beresp.status>=500&&beresp.status<600){/* deliver stale if the object is available */if(stale.exists){return(deliver_stale);}if(req.restarts<1&&(req.request=="GET"||req.request=="HEAD")){restart;}/* else go to vcl_error to deliver a synthetic */error503;}/* set stale_if_error and stale_while_revalidate (customize these values) */setberesp.stale_if_error=86400s;setberesp.stale_while_revalidate=60s;#FASTLY fetchif((beresp.status==500||beresp.status==503)&&req.restarts<1&&(req.request=="GET"||req.request=="HEAD")){restart;}if(req.restarts>0){setberesp.http.Fastly-Restarts=req.restarts;}if(beresp.http.Set-Cookie){setreq.http.Fastly-Cachetype="SETCOOKIE";return(pass);}if(beresp.http.Cache-Control~"private"){setreq.http.Fastly-Cachetype="PRIVATE";return(pass);}/* this code will never be run, commented out for clarity *//*if(beresp.status==500||beresp.status==503){setreq.http.Fastly-Cachetype="ERROR";setberesp.ttl=1s;setberesp.grace=5s;return(deliver);}*/if(beresp.http.Expires||beresp.http.Surrogate-Control~"max-age"||beresp.http.Cache-Control~"(s-maxage|max-age)"){# keep the ttl here}else{# apply the default ttlsetberesp.ttl=3600s;}return(deliver);}sub vcl_hit{#FASTLY hitif(!obj.cacheable){return(pass);}return(deliver);}sub vcl_miss{#FASTLY missreturn(fetch);}sub vcl_deliver{if(resp.status>=500&&resp.status<600){/* restart if the stale object is available */if(stale.exists){restart;}}#FASTLY deliverreturn(deliver);}sub vcl_error{#FASTLY error/* handle 503s */if(obj.status>=500&&obj.status<600){/* deliver stale object if it is available */if(stale.exists){return(deliver_stale);}/* otherwise, return a synthetic *//* include your HTML response here */synthetic{"<!DOCTYPE html><html>Replace this text with the error page you would like to serve to clients if your origin is offline.</html>"};return(deliver);}}sub vcl_pass{#FASTLY pass}sub vcl_log{#FASTLY log}

Why serving stale content may not work as expected

Here are some things to consider if Fastly isn't serving stale content:

Cache: Stale objects are only available for cacheable content.

Shielding: If you don't have shielding enabled, a POP can only serve stale on errors if a request for that cacheable object was made through that POP before. We recommend enabling shielding to increase the probability that stale content on error exists. Shielding is also a good way to quickly refill the cache after a performing a purge all.

Requests: As traffic to your site increases, you're more likely to see stale objects available (even if shielding is disabled). It's reasonable to assume that popular assets will be cached at multiple POPs.

Least Recently Used (LRU): Fastly has an LRU list, so objects are not necessarily guaranteed to stay in cache for the entirety of their TTL (time to live). But eviction is dependent on many factors, including the object's request frequency, its TTL, the POP from which it's being served. For instance, objects with a TTL of longer than 3700s get written to disk, whereas objects with shorter TTLs end up in transient, in-memory-only storage. We recommend setting your TTL to more than 3700s when possible.

Purges: Whenever possible, you should purge content using our soft purge feature. Soft purge allows you to easily mark content as outdated (stale) instead of permanently deleting it from Fastly's caches. If you can't use soft purge, we recommend purging by URL or using surrogate keys instead of performing a purge all.