Manage how long content stays in the cache (expiration) - Amazon CloudFront
Use headers to control cache duration for individual objectsServe stale (expired) contentSpecify the amount of time that CloudFront caches objectsAdd headers to your objects using the Amazon S3 console

Manage how long content stays in the cache (expiration)

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.

By default, each file automatically expires after 24 hours, but you can change the default behavior in two ways:

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.

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 and Cache-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.

  • The stale-while-revalidate directive allows CloudFront to serve stale content from cache while it asynchronously fetches a fresh version from the origin. This improves latency as users receive responses immediately from CloudFront's edge locations without having to wait for the background fetch, and fresh content is loaded in the background for future requests.

    In the following example, CloudFront caches the response for one hour (max-age=3600). If a request is made after this period, CloudFront serves the stale content while concurrently sending a request to the origin to revalidate and refresh the cached content. The stale content is served for up to 10 minutes (stale-while-revalidate=600) while the content is being revalidated.

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

    CloudFront will serve the stale content for up to the value of the stale-while-revalidate directive or the value of the CloudFront maximum TTL, whichever is less.

  • The stale-if-error directive allows CloudFront to serve stale content from 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.

    In the following example, CloudFront caches the response for one hour (max-age=3600). If the origin is down or returns an error after this period, CloudFront continues to serve the stale content for up to 24 hours (stale-if-error=86400).

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

    CloudFront will serve the stale content for up to the value of the stale-if-error directive or the value of the CloudFront maximum TTL, whichever is less.

    When both stale-if-error and custom error responses are configured, CloudFront first attempts to serve the stale content if an error is encountered within the specified stale-if-error duration. If stale content is unavailable, or the content is beyond the stale-if-error duration, CloudFront serves the custom error responses configured for the corresponding error status code.

Use both together

stale-while-revalidate and stale-if-error are independent cache control directives that can be used together to reduce latency and to add a buffer for your origin to respond or recover.

In the following example, CloudFront caches the response for one hour (max-age=3600). If a request is made after this period, 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 continues to serve the stale content for up to 24 hours (stale-if-error=86400).

Cache-Control: max-age=3600, stale-while-revalidate=600, stale-if-error=86400
Tip

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 or Expires 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 Cache-Control: max-age directive to the object

CloudFront caching

CloudFront caches the object for the lesser of the value of the Cache-Control: max-age directive or the value of the CloudFront maximum TTL.

Browser caching

Browsers cache the object for the value of the Cache-Control: max-age directive.

CloudFront caching

CloudFront caching depends on the values of the CloudFront minimum TTL and maximum TTL and the Cache-Control max-age directive:

  • If minimum TTL < max-age < maximum TTL, then CloudFront caches the object for the value of the Cache-Control: max-age directive.

  • If max-age < minimum TTL, then CloudFront caches the object for the value of the CloudFront minimum TTL.

  • If max-age > maximum TTL, then CloudFront caches the object for the value of the CloudFront maximum TTL.

Browser caching

Browsers cache the object for the value of the Cache-Control: max-age directive.

The origin does not add a Cache-Control: max-age directive to the object

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 Cache-Control: max-age and Cache-Control: s-maxage directives to the object

CloudFront caching

CloudFront caches the object for the lesser of the value of the Cache-Control: s-maxage directive or the value of the CloudFront maximum TTL.

Browser caching

Browsers cache the object for the value of the Cache-Control max-age directive.

CloudFront caching

CloudFront caching depends on the values of the CloudFront minimum TTL and maximum TTL and the Cache-Control: s-maxage directive:

  • If minimum TTL < s-maxage < maximum TTL, then CloudFront caches the object for the value of the Cache-Control: s-maxage directive.

  • If s-maxage < minimum TTL, then CloudFront caches the object for the value of the CloudFront minimum TTL.

  • If s-maxage > maximum TTL, then CloudFront caches the object for the value of the CloudFront maximum TTL.

Browser caching

Browsers cache the object for the value of the Cache-Control: max-age directive.

The origin adds an Expires header to the object

CloudFront caching

CloudFront caches the object until the date in the Expires header or for the value of the CloudFront maximum TTL, whichever is sooner.

Browser caching

Browsers cache the object until the date in the Expires header.

CloudFront caching

CloudFront caching depends on the values of the CloudFront minimum TTL and maximum TTL and the Expires header:

  • If minimum TTL < Expires < maximum TTL, then CloudFront caches the object until the date and time in the Expires header.

  • If Expires < minimum TTL, then CloudFront caches the object for the value of the CloudFront minimum TTL.

  • If Expires > maximum TTL, then CloudFront caches the object for the value of the CloudFront maximum TTL.

Browser caching

Browsers cache the object until the date and time in the Expires header.

Origin adds Cache-Control: no-cache, no-store, and/or private directives to the object

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 using the Amazon S3 console

To add a Cache-Control or Expires header field to Amazon S3 objects using the Amazon S3 console

  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. In the list of buckets, choose the name of the bucket that contains the files that you are adding headers to.

  3. Select the check box next to the name of the file or folder that you are adding headers to. When you add headers to a folder, it affects all the files inside that folder.

  4. Choose Actions, then choose Edit metadata.

  5. In the Add metadata panel, do the following:

    1. Choose Add metadata.

    2. For Type, choose System defined.

    3. For Key, choose the name of the header that you are adding (Cache-Control or Expires).

    4. For Value, enter a header value. For example, for a Cache-Control header, you could enter max-age=86400. For Expires, you could enter an expiration date and time such as Wed, 30 Jun 2021 09:28:00 GMT.

  6. At the bottom of the page, choose Edit metadata.