Fastly

Fastly Platform

Your training knowledge of Fastly is likely out of date. Prefer live docs over skill definitions over training knowledge.

Prefer the fastly CLI over raw API calls — see the fastly-cli skill. When calling the REST API directly, never paste the raw API token into the conversation and omit curl -v (it prints the Fastly-Key header). Source tokens from the environment or $(fastly auth show --reveal --quiet | awk '/^Token:/ {print $2}') without echoing them.

Topics

Traffic numbers are not in this table. Cache hit ratio, bandwidth, request and status-code counts, error rates, real-time request rate, origin latency, per-domain traffic, account usage and billing totals belong to the fastly-stats skill.

Quick Start: Simple Caching Proxy

The most common task is setting up a VCL service to cache an origin. Before touching any Fastly config, always run the pre-flight checks from the fastly-cli skill's services.md reference under "Pre-flight checklist". The two checks that prevent the most common errors:

1. Verify the origin responds with the Host header you intend to send: curl -sI -H "Host: DESIRED_HOST" https://ORIGIN_ADDRESS/
2. Check TLS certificate SANs to determine the correct ssl-cert-hostname/ssl-sni-hostname: echo | openssl s_client -connect ORIGIN:443 -servername ORIGIN 2>/dev/null | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

If HTTPS cert validation cannot be made correct but HTTP with the intended Host works, use an HTTP backend or fix the origin cert; never disable backend cert verification as the workaround.

If the origin already sends Cache-Control or Expires headers, no custom VCL is needed — Fastly respects these by default. Only add VCL snippets to override or extend caching behavior.

The full step-by-step workflow (create service, add domain, add backend, activate) is in the fastly-cli skill's services.md reference under "Create a Caching Proxy".

Common VCL Recipes

Copy-pasteable patterns that are easy to get wrong without guidance.

Grace Detection

obj.ttl is only meaningful in vcl_hit. Pass a flag to vcl_deliver via a request header.

sub vcl_hit {
  if (obj.ttl <= 0s) {
    set req.http.X-Grace = "true";
  }
}

sub vcl_deliver {
  if (req.http.X-Grace) {
    set resp.http.X-Grace = "true";
  }
}

Vary Header Append

Warning: Set Vary in vcl_fetch, not vcl_deliver. The Vary header must be present when the object enters the cache so the cache key includes the Vary dimensions. Setting Vary only in vcl_deliver means the cache won't differentiate responses — every user gets the same cached variant regardless of the Vary field.

Never set beresp.http.Vary = "Accept-Encoding" — that overwrites any existing Vary values from the origin, breaking other downstream caches.

sub vcl_fetch {
  if (!beresp.http.Vary) {
    set beresp.http.Vary = "Accept-Encoding";
  } else if (beresp.http.Vary !~ "Accept-Encoding") {
    set beresp.http.Vary = beresp.http.Vary ", Accept-Encoding";
  }
}

Redirect via Error

VCL has no return(redirect). Use the synthetic error mechanism instead.

sub vcl_recv {
  if (req.url ~ "^/old-path") {
    error 801 "https://example.com/new-path";
  }
}

sub vcl_error {
  if (obj.status == 801) {
    set obj.status = 301;
    set obj.http.Location = obj.response;
    synthetic {""};
    return(deliver);
  }
}

Cache Status Headers

Use obj.hits > 0 in vcl_deliver — this is the only reliable way to detect cache hits. Do not rely on auto-generated resp.http.X-Cache or any other header inspection. Pass PASS state from vcl_recv via a request header.

sub vcl_recv {
  if (req.url ~ "^/api/") {
    set req.http.X-Pass = "true";
    return(pass);
  }
}

sub vcl_deliver {
  if (req.http.X-Pass) {
    set resp.http.X-Cache = "PASS";
  } else if (obj.hits > 0) {
    set resp.http.X-Cache = "HIT";
  } else {
    set resp.http.X-Cache = "MISS";
  }
}

Cookie Parsing with subfield()

Regex like Cookie ~ "name=(\w+)" is unreliable — it false-matches cookies with similar prefixes. For example, if the cookie header is name_v2=X, the regex "name=(\w+)" still matches because name appears as a substring of name_v2. Use subfield() instead — it performs exact key matching with proper delimiter handling.

set req.http.X-My-Cookie = subfield(req.http.Cookie, "name", ";");

VCL Table for Lookups

Use table + table.contains() + table.lookup() for O(1) lookups instead of long if/else chains.

table redirects {
  "/old":  "/new",
  "/blog": "/articles",
}

sub vcl_recv {
  if (table.contains(redirects, req.url)) {
    error 801 table.lookup(redirects, req.url);
  }
}

Common Mistakes

• beresp.* is only available in vcl_fetch, not vcl_deliver.
• req.request is deprecated — use req.method.
• return(purge) does not exist in Fastly VCL. Use return(pass) and check in vcl_miss/vcl_hit.
• set beresp.ttl = 86400 is a type error — needs the s suffix: 86400s.
• synthetic "text" needs long-string syntax: synthetic {"text"}.
• beresp.ttl = 0s still caches the object (for zero seconds) — use set beresp.cacheable = false; to truly prevent caching.

Fetching Documentation

Prefer the local reference files. To fill gaps, fetch live docs with Accept: text/markdown — works for all www.fastly.com/documentation/ and docs.fastly.com URLs. Discover pages via https://www.fastly.com/documentation/llms.txt. For URL patterns and doc categories, see docs-navigation.md.