[Cache] Document CDN-Cache-Control as a BYPASS cause

[ngayerie]

Two small follow-ups to #32423.

What

• Add a bullet to the BYPASS lists in cache-responses.mdx and investigating-uncached-responses.mdx documenting Cloudflare-CDN-Cache-Control and CDN-Cache-Control, with the precedence chain Cloudflare-CDN-Cache-Control > CDN-Cache-Control > Cache-Control. Uses a concrete example so the reader sees that a cacheable Cache-Control alongside a non-cacheable CDN-Cache-Control still produces BYPASS.
• Rewrite the Age callout in cache-responses.mdx and the corresponding HIT-verification bullet in the troubleshooting page. Both currently mention CacheTieredFill=true, which is an http_requests Logpush field, not an HTTP header — readers cannot observe it on a response.

Why

Neither BYPASS list mentioned Cloudflare-CDN-Cache-Control or CDN-Cache-Control. When both Cache-Control and CDN-Cache-Control are set, CDN-Cache-Control wins per CDN-Cache-Control, so a reader debugging a BYPASS while only looking at Cache-Control has no signal from these pages that another header is in play.

@zaidoon1 for review.

[cloudflare-docs-bot]

Review

⚠️ 1 warning found in commit 7642ef2.

👉 Fix in your agent 👈

Fix the following review findings in PR #32569 (https://github.com/cloudflare/cloudflare-docs/pull/32569).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.

---

## Code Review

### Warnings (1)

#### CR-d79577e2bb37 · Incomplete Authorization caveat for Cloudflare-CDN-Cache-Control
- **File:** `src/content/docs/cache/troubleshooting/investigating-uncached-responses.mdx` line 44
- **Issue:** The new bullet says `no-cache`, `max-age=0`, or `s-maxage=0` in `Cloudflare-CDN-Cache-Control` or `CDN-Cache-Control` ‘do not produce `BYPASS`’. However, the existing Origin Cache Control docs state that when `Cloudflare-Cdn-Cache-Control` is set, OCC is forced on and the Authorization logic allows caching only if `s-maxage`, `must-revalidate`, or `public` is also present. So a request that includes an `Authorization` header and `Cloudflare-CDN-Cache-Control: no-cache` or `max-age=0` would still return `BYPASS`, contradicting the unqualified claim.
- **Fix:** Qualify the statement so it does not contradict the Authorization interaction — for example, add ‘unless the request includes an `Authorization` header’ or cross-reference the existing Authorization bullet.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (1)

File

Issue

cache/troubleshooting/investigating-uncached-responses.mdx line 44

Incomplete Authorization caveat for Cloudflare-CDN-Cache-Control — The new bullet says no-cache, max-age=0, or s-maxage=0 in Cloudflare-CDN-Cache-Control or CDN-Cache-Control ‘do not produce BYPASS’. However, the existing Origin Cache Control docs state that when Cloudflare-Cdn-Cache-Control is set, OCC is forced on and the Authorization logic allows caching only if s-maxage, must-revalidate, or public is also present. So a request that includes an Authorization header and Cloudflare-CDN-Cache-Control: no-cache or max-age=0 would still return BYPASS, contradicting the unqualified claim. Fix: Qualify the statement so it does not contradict the Authorization interaction — for example, add ‘unless the request includes an Authorization header’ or cross-reference the existing Authorization bullet.

Conventions

_{No convention issues found.}

Style Guide Review

_{No style-guide issues found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/cache/	@cloudflare/product-owners, @ack-cf, @zaidoon1, @mbullock1986

[github-actions]

Preview URL: https://7642ef27.preview.developers.cloudflare.com
Preview Branch URL: https://ngayerie-cache-cdn-cache-control-bypass.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/cache/concepts/cache-responses/	https://ngayerie-cache-cdn-cache-control-bypass.preview.developers.cloudflare.com/cache/concepts/cache-responses/
https://developers.cloudflare.com/cache/troubleshooting/investigating-uncached-responses/	https://ngayerie-cache-cdn-cache-control-bypass.preview.developers.cloudflare.com/cache/troubleshooting/investigating-uncached-responses/

[foreseaz]

good call, maybe we want to mention Surrogate-Control too.

Cloudflare-CDN-CC > CDN-CC > Surrogate-Control > Cache-Control

cc @zaidoon1

[ngayerie]

Hi @mbullock1986 , @zaidoon1
What do you think? Should we mention Surrogate-Control in this page?

[foreseaz]

Both changes LGTM. Left some nits to make the existing change more clear, thanks for the effort @ngayerie

[ngayerie]

Hi @mbullock1986 @zaidoon1
Would it be possible for you to review/approve this PR?
Thanks!

[zaidoon1]

Checked the CDN-Cache-Control and Age claims against actual behavior. The BYPASS bullet's core point is right, but a few details need tightening. Comments inline.

[ngayerie]

[AI] Thanks @zaidoon1 — all 5 comments applied in 26b189cb.

cache-responses.mdx

1. Age callout scope — dropped at that cache, kept it network-wide, and added the Tiered Cache clarification (HIT served locally can carry an Age inherited from an upper tier, so the value can be older than the last local fill).
2. Age status enumeration — rewritten by cf-cache-status: Age is set on HIT, STALE, UPDATING. It is absent on MISS, on EXPIRED and REVALIDATED when the request revalidated against the origin, and on DYNAMIC, BYPASS, NONE/UNKNOWN. Origin-set Age on an uncacheable response is proxied to the client unchanged.
3. CDN-Cache-Control BYPASS bullet — named the directives (only no-store and bare private produce BYPASS; no-cache/max-age=0/s-maxage=0 produce MISS then REVALIDATED/EXPIRED), dropped the Origin Cache Control condition (these headers follow OCC-style semantics regardless of the zone setting).
4. CDN-Cache-Control BYPASS bullet — added the Edge Cache TTL override, same as Cache-Control: no-store.

investigating-uncached-responses.mdx

3. CDN-Cache-Control BYPASS bullet — mirrored the same corrections, and reframed the troubleshooting angle: noted that Cloudflare does not forward Cloudflare-CDN-Cache-Control to the client, so if a reader sees BYPASS without a visible CDN-Cache-Control header the next step is checking what the origin actually sent (or dropping the header at origin and retesting), not "inspect every response header".

Also reconciled the HIT verification bullet on the same page with your Age scope correction — a fresh local fill from an upper tier can already report a large Age, so "may be absent" was wrong.

[zaidoon1]

Latest addresses everything I raised. One clause got lost in the rewrite that I'd put back, plus a couple of small things.

[ngayerie]

[AI] Thanks @zaidoon1 — all 4 comments applied in f1675c05.

1. Age reset rule — qualified as revalidation against the origin, matching the phrasing on the paragraph below. A lower tier revalidating against an upper tier that still has the object picks up the upper tier's age, so the unqualified revalidation was wrong for Tiered Cache.
2. Semicolon on cache-responses.mdx line 58 — split into two sentences.
3. Six-sentence bullet on the troubleshooting page — pulled the no-cache/max-age=0/s-maxage=0 clarification into its own bullet. It's the clause that tells the reader to look under Repeated MISS instead, so it earns the separate bullet. That split also removed the matching semicolon on the troubleshooting page.
4. HIT verify Age bullet — restored the absent-on-fill case: on the request that fills a lower-tier data center from an upper tier, the client gets HIT with no Age at all, because the local data center has not served it from cache yet. Subsequent requests include Age, and with Tiered Cache the value can already be large — kept the "increases on subsequent requests" signal you called out.

[zaidoon1]

Two small ones on the new bullet, neither blocking.

[ngayerie]

[AI] Thanks @zaidoon1 — both applied in 6afd6b1b.

• "these headers" reference — replaced with the explicit header names at the start of the bullet, so it stands alone for a scanner reading only the bolded openings.
• Pointer to Repeated MISS — dropped. That section covers cache key variance and eviction, neither of which matches the MISS → REVALIDATED/EXPIRED pattern this bullet describes, so it was sending readers the wrong way. Kept the sequence description — Confirm the response reaches cache already covers verification with those same two statuses.

[mbullock1986]

based on Zaidoon's comments being fixed

[ngayerie]

Hi @zaidoon1
Happy for me to merge?