Resources · Guides

Putting a CDN in front of ImagePipe without breaking automatic format negotiation

How to add a CDN or reverse proxy in front of ImagePipe without letting it silently break the Accept-based format negotiation, and what to check about Vary: Accept.

Diagram of a CDN placed between a browser and the ImagePipe server
October 20, 2026

ImagePipe negotiates image format per request using the Accept header sent by the browser: AVIF first on Pro and above, then WebP, then a JPEG/PNG fallback. When you put a CDN or reverse proxy in front of ImagePipe, that CDN becomes a new caching layer sitting between the browser and ImagePipe's own permanent disk cache. If the CDN caches the image response without taking the Accept header into account, it stores a single variant, say AVIF, and starts serving that same cached response to every visitor requesting the same URL, including browsers that never advertised AVIF support.

The practical symptom is inconsistent: some visitors see a broken or unexpectedly heavy image, others see nothing wrong, depending on which variant got cached first and which edge node answered. This is not an ImagePipe bug : ImagePipe already sends the correct response for each request it receives, the problem sits one layer above, in the CDN's own caching decision.

Before enabling a CDN in front of ImagePipe, check whether it honours Vary: Accept on responses. Most CDNs support this but do not enable it by default, and some cap the number of Vary-based cache variants stored per URL. If your CDN has no support for Vary-based caching at all, the safer route is to segment the cache key yourself, for example by including a normalized format bucket in the edge rule, so AVIF, WebP and JPEG/PNG responses never share the same cache entry.

Once configured, verify it by requesting the same image URL twice through the CDN, once with an Accept header excluding AVIF and WebP, once with a modern browser's default header, then compare the Content-Type returned each time. If both requests return the same cached bytes, the CDN still is not respecting the negotiation and needs further tuning before going live.

Back to guides