Skip to main content

Exclude Images from Processing (Whitelist)

About the whitelist feature

What is it? Whitelist lets you exclude specific, known-problematic images (e.g. an image that fails to process well) from Image Stack processing, so they are served unchanged instead of with a bad conversion.

Enable whitelist

Whitelist is included in the Image Optimizer service. Configure via environment variables.

IMAGE_WHITELIST=logo.png,broken-photo.jpg
VariableTypeDefaultDescription
IMAGE_WHITELISTstring(empty)Comma-separated list of image filenames to skip processing for and serve unchanged

Matching behavior

  • Matching is by filename only (the last path segment), case-insensitive, and ignores the query string — so /any/path/logo.png and /any/path/logo.png?width=200 are both skipped.
  • Because matching is filename-only, two different images that happen to share the same filename in different folders will both be skipped.
  • When a request is skipped this way, the original response (headers and body) is served unchanged.

Check HTTP headers

curl -I https://your-cdn.com/logo.png

Expected: X-Img-Skip-Reason: whitelisted

Limitations

  • Matching is filename-only, not full path — ensure whitelisted filenames are specific enough to avoid unintentionally skipping unrelated images that share the same name.

Troubleshooting

Image still processed: Verify the filename (case-insensitive, no path) is listed in IMAGE_WHITELIST and matches exactly. Wrong image skipped: Two different images sharing the same filename will both be skipped; rename one if this is not desired.

IMAGE_WHITELIST=logo.png,broken-photo.jpg