Serving stale content
Last updated 2021-04-21
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.
TIP
For more information on serving stale content, see our documentation on staleness and revalidation.
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.
Fastly builds on the behavior proposed in RFC 5861 "HTTP Cache-Control Extensions for Stale Content" by Mark Nottingham, which is under consideration for inclusion in Google's Chrome browser.
Enabling serve stale
NOTE
If you've already enabled serving stale content on an error via custom VCL, adding this feature via the web interface will set a different stale TTL. To avoid this, check your custom VCL and remove the stale-if-error
statement before enabling this feature via the web interface.
To enable serving stale content on an error via the web interface for the default TTL period (43200 seconds or 12 hours), follow the steps below.
- Log in to the Fastly web interface.
- From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
- Click Edit configuration and then select the option to clone the active version.
- Click Settings.
Click the Serve stale switch to automatically enable serving stale content for the default TTL period of 43200 seconds (12 hours).
- Click Activate to deploy your configuration changes.
Manually enabling serve stale
You can manually enable serving stale content by adding a stale-while-revalidate
or stale-if-error
directive 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-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.
In the context of Varnish, there are three ways an origin can fail:
- The origin can be marked as unhealthy by failing health checks.
- 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 sendingstale_if_error
in Surrogate-Control or Cache-Control from origin, remove this entire line.set beresp.stale_while_revalidate = 60s;
controls how long thestale_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 thatstale_while_revalidate
overridesstale_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 sendingstale_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.
1sub vcl_recv {2 /* if shielding is enabled, the below code is required */3 if (fastly.ff.visits_this_service != 0) {4 set req.max_stale_while_revalidate = 0s;5 }6
7#FASTLY recv8
9 if (req.method != "HEAD" && req.method != "GET" && req.method != "FASTLYPURGE") {10 return(pass);11 }12
13 return(lookup);14}15
16sub vcl_fetch {17 /* handle 5XX (or any other unwanted status code) */18 if (beresp.status >= 500 && beresp.status < 600) {19
20 /* deliver stale if the object is available */21 if (stale.exists) {22 return(deliver_stale);23 }24
25 if (req.restarts < 1 && (req.method == "GET" || req.method == "HEAD")) {26 restart;27 }28
29 /* else go to vcl_error to deliver a synthetic */30 error beresp.status;31 }32
33 /* set stale_if_error and stale_while_revalidate (customize these values) */34 set beresp.stale_if_error = 86400s;35 set beresp.stale_while_revalidate = 60s;36
37#FASTLY fetch38
39 if ((beresp.status == 500 || beresp.status == 503) && req.restarts < 1 && (req.method == "GET" || req.method == "HEAD")) {40 restart;41 }42
43 if (req.restarts > 0) {44 set beresp.http.Fastly-Restarts = req.restarts;45 }46
47 if (beresp.http.Set-Cookie) {48 set req.http.Fastly-Cachetype = "SETCOOKIE";49 return(pass);50 }51
52 if (beresp.http.Cache-Control ~ "private") {53 set req.http.Fastly-Cachetype = "PRIVATE";54 return(pass);55 }56
57 /* this code will never be run, commented out for clarity */58 /* if (beresp.status == 500 || beresp.status == 503) {59 set req.http.Fastly-Cachetype = "ERROR";60 set beresp.ttl = 1s;61 set beresp.grace = 5s;62 return(deliver);63 } */64
65 if (beresp.http.Expires || beresp.http.Surrogate-Control ~ "max-age" || beresp.http.Cache-Control ~ "(s-maxage|max-age)") {66 # keep the ttl here67 } else {68 # apply the default ttl69 set beresp.ttl = 3600s;70 }71
72 return(deliver);73}74
75sub vcl_hit {76#FASTLY hit77
78 if (!obj.cacheable) {79 return(pass);80 }81 return(deliver);82}83
84sub vcl_miss {85#FASTLY miss86 return(fetch);87}88
89sub vcl_deliver {90
91#FASTLY deliver92 return(deliver);93}94
95sub vcl_error {96#FASTLY error97
98 /* handle 503s */99 if (obj.status >= 500 && obj.status < 600) {100
101 /* deliver stale object if it is available */102 if (stale.exists) {103 return(deliver_stale);104 }105
106 /* otherwise, return a synthetic */107
108 /* include your HTML response here */109 synthetic {"<!DOCTYPE html><html>Replace this text with the error page you would like to serve to clients if your origin is offline.</html>"};110 return(deliver);111 }112
113}114
115sub vcl_pass {116#FASTLY pass117}118
119sub vcl_log {120#FASTLY log121}
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.
- VCL: Setting
req.hash_always_miss
orreq.hash_ignore_busy
variable totrue
invalidates the effect ofstale-while-revalidate
. - 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 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 3700s or longer 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.
Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.