You can control how long your files stay in a CloudFront cache before CloudFront forwards another request to your origin. Reducing the duration allows you to serve dynamic content. Increasing the duration means that your users get better performance because your files are more likely to be served directly from the edge cache. A longer duration also reduces the load on your origin.
Typically, CloudFront serves a file from an edge location until the cache duration that you specified passes—that is, until the file expires. After it expires, the next time the edge location gets a request for the file, CloudFront forwards the request to the origin to verify that the cache contains the latest version of the file. The response from the origin depends on whether the file has changed:
-
If the CloudFront cache already has the latest version, the origin returns a status code
304 Not Modified
. -
If the CloudFront cache does not have the latest version, the origin returns a status code
200 OK
and the latest version of the file.
If a file in an edge location isn't frequently requested, CloudFront might evict the file—remove the file before its expiration date—to make room for files that have been requested more recently.
We recommend managing your cache duration by updating your distribution's cache policy. If you opt out of using a cache policy, the default TTL (Time to Live) is 24 hours, but you can update the following settings to override the default:
-
To change the cache duration for all files that match the same path pattern, you can change the CloudFront settings for Minimum TTL, Maximum TTL, and Default TTL for a cache behavior. For information about the individual settings, see Minimum TTL, Maximum TTL, and Default TTL in Distribution settings reference.
-
To change the cache duration for an individual file, you can configure your origin to add a
Cache-Control
header with themax-age
ors-maxage
directive, or anExpires
header to the file. For more information, see Use headers to control cache duration for individual objects.
For more information about how Minimum TTL, Default
TTL, and Maximum TTL interact with the
max-age
and s-maxage
directives and the
Expires
header field, see Specify the amount of time that CloudFront caches
objects.
You can also control how long errors (for example, 404 Not Found
) stay in
a CloudFront cache before CloudFront tries again to get the requested object by forwarding another
request to your origin. For more information, see How CloudFront processes HTTP 4xx and 5xx status codes from
your origin.
Topics
Use headers to control cache
duration for individual objects
You can use the Cache-Control
and Expires
headers to
control how long objects stay in the cache. Settings for Minimum
TTL, Default TTL, and Maximum TTL
also affect cache duration, but here's an overview of how headers can
affect cache duration:
-
The
Cache-Control max-age
directive lets you specify how long (in seconds) that you want an object to remain in the cache before CloudFront gets the object again from the origin server. The minimum expiration time CloudFront supports is 0 seconds. The maximum value is 100 years. Specify the value in the following format:Cache-Control: max-age=
seconds
For example, the following directive tells CloudFront to keep the associated object in the cache for 3600 seconds (one hour):
Cache-Control: max-age=3600
If you want objects to stay in CloudFront edge caches for a different duration than they stay in browser caches, you can use the
Cache-Control max-age
andCache-Control s-maxage
directives together. For more information, see Specify the amount of time that CloudFront caches objects. -
The
Expires
header field lets you specify an expiration date and time using the format specified in RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1 Section 3.3.1, Full Date, for example: Sat, 27 Jun 2015 23:59:59 GMT
We recommend that you use the Cache-Control max-age
directive instead
of the Expires
header field to control object caching. If you specify
values both for Cache-Control max-age
and for Expires
,
CloudFront uses only the value of Cache-Control max-age
.
For more information, see Specify the amount of time that CloudFront caches objects.
You cannot use the HTTP Cache-Control
or Pragma
header
fields in a GET
request from a viewer to force CloudFront to go back to the
origin server for the object. CloudFront ignores those header fields in viewer
requests.
For more information about the Cache-Control
and Expires
header fields, see the following sections in RFC 2616, Hypertext Transfer
Protocol -- HTTP/1.1:
Serve stale (expired) content
CloudFront supports the Stale-While-Revalidate
and
Stale-If-Error
cache control directives. You can use these
directives to specify how long stale content is available for viewers.
Stale-While-Revalidate
This directive allows CloudFront to serve stale content from the cache while CloudFront asynchronously fetches a fresh version from the origin. This improves latency as viewers receive responses immediately from edge locations without having to wait for the background fetch. Fresh content is loaded in the background for future requests.
Example: Stale-While-Revalidate
CloudFront does the following when you set the Cache-Control
header
to use these directives.
Cache-Control: max-age=3600, stale-while-revalidate=600
-
CloudFront will cache a response for one hour (
max-age=3600
). -
If a request is made after this duration, CloudFront serves the stale content, while concurrently sending a request to the origin to revalidate and refresh the cached content.
-
While the content is being revalidated, CloudFront serves the stale content up to 10 minutes (
stale-while-revalidate=600
).
Note
CloudFront will serve the stale content up to the value of the
stale-while-revalidate
directive or the value of the CloudFront
maximum TTL, whichever
is less. After the maximum TTL duration, the stale object won't be
available from the edge cache, regardless of the
stale-while-revalidate
value.
Stale-If-Error
This directive allows CloudFront to serve stale content from the cache if the origin is unreachable or returns an error code that is between 500 and 600. This ensures that viewers can access content even during an origin outage.
Example: Stale-If-Error
CloudFront does the following when you set the Cache-Control
header
to use these directives.
Cache-Control: max-age=3600, stale-if-error=86400
-
CloudFront caches the response for one hour (
max-age=3600
). -
If the origin is down or returns an error after this duration, CloudFront continues to serve the stale content for up to 24 hours (
stale-if-error=86400
) -
If you configured custom error responses, CloudFront will attempt to serve the stale content if an error is encountered within the specified
stale-if-error
duration. If the stale content is unavailable, CloudFront will then serve the custom error responses that you configured for the corresponding error status code. For more information, see Generate custom error responses.
Notes
-
CloudFront will serve the stale content up to the value of the
stale-if-error
directive or the value of the CloudFront maximum TTL, whichever is less. After the maximum TTL duration, the stale object won't be available from the edge cache, regardless of thestale-if-error
value. -
If you don't configure
stale-if-error
or custom error responses, CloudFront will return the stale object or forward the error response back to viewer, depending on whether the requested object is in the edge cache or not. For more information, see How CloudFront processes errors if you haven't configured custom error pages.
Use both directives
Both stale-while-revalidate
and stale-if-error
are
independent cache control directives that you can use together to reduce latency
and to add a buffer for your origin to respond or recover.
Example: Using both directives
CloudFront does the following when you set the Cache-Control
header
to use the following directives.
Cache-Control: max-age=3600, stale-while-revalidate=600, stale-if-error=86400
-
CloudFront caches the response for one hour (
max-age=3600
). -
If a request is made after this duration, CloudFront serves the stale content for up to 10 minutes (
stale-while-revalidate=600
) while the content is being revalidated. -
If the origin server returns an error while CloudFront attempts to revalidate the content, CloudFront will continue to serve the stale content for up to 24 hours (
stale-if-error=86400
).
Caching is a balance between performance and freshness. Using directives like
stale-while-revalidate
and stale-if-error
can
enhance performance and user experience, but make sure the configurations align
with how fresh you want your content to be. Stale content directives are best
suited for use cases where content needs to be refreshed but having the latest
version is non-essential. Additionally, if your content doesn’t change or rarely
changes, stale-while-revalidate
could add unnecessary network
requests. Instead, consider setting a long cache duration.
Specify the amount of time that CloudFront caches
objects
To control the amount of time that CloudFront keeps an object in the cache before sending another request to the origin, you can:
-
Set the minimum, maximum, and default TTL values in a CloudFront distribution's cache behavior. You can set these values in a cache policy attached to the cache behavior (recommended), or in the legacy cache settings.
-
Include the
Cache-Control
orExpires
header in responses from the origin. These headers also help determine how long a browser keeps an object in the browser cache before sending another request to CloudFront.
The following table explains how the Cache-Control
and
Expires
headers sent from the origin work together with the TTL
settings in a cache behavior to affect caching.
Origin headers | Minimum TTL = 0 | Minimum TTL > 0 |
---|---|---|
The origin adds a |
CloudFront caching CloudFront caches the object for the lesser of the value of the
Browser caching Browsers cache the object for the value of the
|
CloudFront caching CloudFront caching depends on the values of the CloudFront minimum TTL and
maximum TTL and the
Browser caching Browsers cache the object for the value of the
|
The origin does not add a
|
CloudFront caching CloudFront caches the object for the value of the CloudFront default TTL. Browser caching Depends on the browser. |
CloudFront caching CloudFront caches the object for the greater of the value of the CloudFront minimum TTL or default TTL. Browser caching Depends on the browser. |
The origin adds |
CloudFront caching CloudFront caches the object for the lesser of the value of the
Browser caching Browsers cache the object for the value of the
|
CloudFront caching CloudFront caching depends on the values of the CloudFront minimum TTL and
maximum TTL and the
Browser caching Browsers cache the object for the value of the
|
The origin adds an |
CloudFront caching CloudFront caches the object until the date in the
Browser caching Browsers cache the object until the date in the
|
CloudFront caching CloudFront caching depends on the values of the CloudFront minimum TTL and
maximum TTL and the
Browser caching Browsers cache the object until the date and time in the
|
Origin adds |
CloudFront and browsers respect the headers. |
CloudFront caching CloudFront caches the object for the value of the CloudFront minimum TTL. See the warning below this table. Browser caching Browsers respect the headers. |
Warning
If your minimum TTL is greater than 0, CloudFront uses the cache policy’s minimum
TTL, even if the Cache-Control: no-cache
, no-store
,
and/or private
directives are present in the origin headers.
If the origin is reachable, CloudFront gets the object from the origin and returns it to the viewer.
If the origin is unreachable and the minimum or maximum TTL value is greater than 0, CloudFront will serve the object that it got from the origin previously.
To avoid this behavior, include the Cache-Control:
stale-if-error=0
directive with the object returned from the origin.
This causes CloudFront to return an error in response to future requests if the origin
is unreachable, rather than returning the object that it got from the origin
previously.
For information about how to change settings for distributions using the CloudFront console, see Update a distribution. For information about how to change settings for distributions using the CloudFront API, see UpdateDistribution.
Add headers to your objects by using the Amazon S3
console
You can add the Cache-Control
or Expires
header field to your
Amazon S3 objects. To do so, you modify the metadata fields for the object.
To add a Cache-Control
or Expires
header field to Amazon S3
objects
-
Follow the procedure in the Replacing system-defined metadata section on the Editing object metadata in the Amazon S3 console topic in the Amazon S3 User Guide.
-
For Key, choose the name of the header that you are adding (Cache-Control or Expires).
-
For Value, enter a header value. For example, for a
Cache-Control
header, you could entermax-age=86400
. ForExpires
, you could enter an expiration date and time such asWed, 30 Jun 2021 09:28:00 GMT
. -
Follow the rest of the procedure to save your metadata changes.