Invalidations & Cache-Control Strategy

You shipped a new build, but edges are still serving the old file until its TTL expires. Two tools fix this: an invalidation that actively removes objects from every edge, and a cache-busting strategy that changes the URL so the new content has a new cache key and the old copy simply ages out.

They are not equivalent. Invalidations cost money past a free allowance and take time to propagate; versioned URLs are free and instant. This page shows how to invalidate via the SDK and when to avoid it entirely.

Recipe

CreateInvalidation takes an InvalidationBatch with a Paths list and a unique CallerReference. Each path is an absolute URL path, optionally ending in a * wildcard.

# --- Python (boto3) ---
import boto3, time
 
cf = boto3.client("cloudfront", region_name="us-east-1")
resp = cf.create_invalidation(
    DistributionId="E1234ABCDEF",
    InvalidationBatch={
        "CallerReference": f"deploy-{int(time.time())}",   # unique per call
        "Paths": {"Quantity": 2, "Items": ["/index.html", "/css/*"]},
    },
)
print(resp["Invalidation"]["Id"], resp["Invalidation"]["Status"])  # InProgress

// --- TypeScript (AWS SDK v3) ---
import { CloudFrontClient, CreateInvalidationCommand } from "@aws-sdk/client-cloudfront";
 
const cf = new CloudFrontClient({ region: "us-east-1" });
const resp = await cf.send(new CreateInvalidationCommand({
  DistributionId: "E1234ABCDEF",
  InvalidationBatch: {
    CallerReference: `deploy-${Date.now()}`,   // unique per call
    Paths: { Quantity: 2, Items: ["/index.html", "/css/*"] },
  },
}));
console.log(resp.Invalidation?.Id, resp.Invalidation?.Status);  // InProgress

The call returns immediately with Status: "InProgress". The removal propagates to all edges over the next seconds to a few minutes. Note the same Quantity-must-match-Items rule from the rest of the CloudFront API applies to Paths.

Working Example

For a deploy script you usually want to wait until the invalidation completes before declaring the release done. Track it with the invalidation_completed waiter or by polling GetInvalidation.

# --- Python (boto3) ---
import boto3, time
 
cf = boto3.client("cloudfront", region_name="us-east-1")
inv = cf.create_invalidation(
    DistributionId="E1234ABCDEF",
    InvalidationBatch={
        "CallerReference": f"deploy-{int(time.time())}",
        "Paths": {"Quantity": 1, "Items": ["/*"]},   # one path, clears everything
    },
)
inv_id = inv["Invalidation"]["Id"]
 
cf.get_waiter("invalidation_completed").wait(
    DistributionId="E1234ABCDEF", Id=inv_id,
)
print("invalidation complete")

// --- TypeScript (AWS SDK v3) ---
import {
  CloudFrontClient, CreateInvalidationCommand, waitUntilInvalidationCompleted,
} from "@aws-sdk/client-cloudfront";
 
const cf = new CloudFrontClient({ region: "us-east-1" });
const inv = await cf.send(new CreateInvalidationCommand({
  DistributionId: "E1234ABCDEF",
  InvalidationBatch: {
    CallerReference: `deploy-${Date.now()}`,
    Paths: { Quantity: 1, Items: ["/*"] },   // one path, clears everything
  },
}));
const invId = inv.Invalidation!.Id!;
 
await waitUntilInvalidationCompleted(
  { client: cf, maxWaitTime: 600 },
  { DistributionId: "E1234ABCDEF", Id: invId },
);
console.log("invalidation complete");

The /* wildcard invalidates the entire distribution and, importantly, counts as a single path for billing. Listing 300 individual files, by contrast, counts as 300 paths. This billing model shapes the whole strategy below.

Deep Dive

The Billing Model

CloudFront gives a monthly free allowance of invalidation paths (1,000 at the time of writing), then bills per path beyond that. The unit is the path, not the invalidation request:

• ["/index.html"] is one path.
• ["/a.js", "/b.js", "/c.js"] is three paths.
• ["/*"] is one path but clears everything.

So a naive deploy that invalidates every changed file individually can rack up thousands of billable paths on a large site, while a single /* costs one path. The trade-off is that /* also throws away cache for files that did not change, forcing edges to refill them from the origin and briefly raising origin load and latency.

Wildcards and Path Rules

Paths are absolute (they start with /) and URL-encoded. A trailing * is the only wildcard and matches any suffix: /css/* clears everything under /css/. Paths match against the object path only, not query strings - if your cache key includes a query string, invalidating /page clears every variant of /page regardless of query. There is a limit on wildcard invalidations in progress at once, so batch related paths into a single request rather than firing many.

Versioned URLs: The Preferred Default

The cheaper and faster strategy is to never invalidate at all. Give each build's assets a content-hashed filename - app.9f2a1c.js instead of app.js - so a new build produces a new URL with a new cache key. The old file ages out on its own TTL while the new one is fetched fresh on first request. Because the cache key changed, there is nothing to invalidate.

Pair this with long-lived Cache-Control on the hashed assets and a short TTL (or no-cache) on the small, unhashed HTML entry point that references them:

# Fingerprinted assets - cache forever, they never change under this name
Cache-Control: public, max-age=31536000, immutable
 
# HTML entry point - always revalidate so it points at the newest assets
Cache-Control: no-cache

The origin sends these headers; CloudFront honors them within the behavior's MinTTL/MaxTTL. With this setup a deploy needs zero invalidations: only the tiny HTML is ever re-fetched, and it in turn points browsers and edges at the new fingerprinted files. Reserve CreateInvalidation for the rare case where you must purge already-served content immediately - a mistaken publish, a legal takedown, or an emergency rollback.

Gotchas

• Reusing a CallerReference. If you reuse one with a different batch you get an error; if you reuse it with the same batch you get the previous invalidation back instead of a new one. Generate a fresh reference per call.
• Invalidating file-by-file on every deploy. This is the classic cost leak. Use versioned URLs so most deploys need no invalidation at all.
• Assuming invalidation is instant. It returns InProgress and propagates over seconds to minutes. Wait on completion if correctness depends on it.
• Forgetting query strings. Invalidation matches the path only. /page clears all query-string variants of /page; you cannot invalidate a single query variant.
• Quantity not matching Paths.Items. As everywhere in the CloudFront API, the count must equal the list length.
• Relying on /* to fix a stale HTML loop. If your HTML is cached long, viewers keep loading old markup; fix the root cause with no-cache on HTML rather than invalidating repeatedly.

Alternatives

• Versioned / fingerprinted URLs (described above) are the default for static assets - free, instant, and safe under rollback.
• Short TTLs let objects expire on their own; good for feeds and dashboards that tolerate a minute of staleness without any invalidation.
• Cache-key design (via a cache policy) can vary content by a query string or header so you never need to purge a shared URL - you just request a different one.
• Origin-driven Cache-Control lets the origin dictate freshness per response, which is often enough that invalidations become the exception, not the routine.

Invalidate only when you must remove already-cached content right now; for routine deploys, change the URL instead.

FAQs

Related

• CloudFront's Edge Caching Model - why an expired TTL revalidates instead of deleting, and what a cache key is.
• Cache Behaviors & Origin Groups - setting per-path caching so invalidation is rarely needed.
• CloudFront via SDK Basics - the distribution these invalidations run against.
• CloudFront via SDK Best Practices - invalidation-cost awareness as a habit.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).