AVIF Conversion in CI/CD: Common Pitfalls

Automating AVIF conversion within Continuous Integration and Continuous Deployment (CI/CD) pipelines can drastically reduce image payloads and improve web performance metrics. However, because AVIF encoding is computationally intensive and structurally different from legacy formats like JPEG and PNG, teams frequently encounter severe operational bottlenecks. This article highlights the most common pitfalls when configuring automated AVIF pipelines and outlines how to prevent them from degrading your build performance and output quality.

1. Uncapped Build Times Due to Aggressive CPU Effort Settings

AVIF relies on the AV1 video codec architecture, making encoding significantly slower than WebP or MozJPEG. A standard pitfall is configuring the encoder (such as libaom, rav1e, or svt-av1) with high compression effort levels (e.g., effort: 8 or speed: 0).

In a CI/CD environment, this creates exponential build times for negligible file size gains:

• The Problem: Moving from an effort level of 4 to 8 often yields only a 2–5% reduction in file size while multiplying CPU encoding time by a factor of 10 or more.
• The Fix: Cap your encoder preset or effort level to a middle tier (typically speed: 4 to 6 in libaom-avif or equivalent). Reserve the most aggressive compression settings only for major release builds or off-pipeline background workers.

2. Inefficient Caching and Re-encoding Unchanged Assets

Pipelines that lack intelligent asset diffing will attempt to convert every repository image on every single pull request or deployment.

• The Problem: Processing hundreds of static images repeatedly drains CI minutes, increases cloud billing costs, and delays deployments.
• The Fix: Implement content-hash caching. Store the processed AVIF files in an external cache (such as an S3 bucket or native CI runner cache) tied to the SHA-256 hash of the source image and the current encoder configuration. Only process images whose source hashes do not exist in the cache.

3. High Concurrency Leading to Out-of-Memory (OOM) Crashes

To speed up processing, developers often use parallel runners or map utilities like p-limit or GNU parallel using the maximum number of available CPU cores.

• The Problem: AVIF encoding requires substantial memory per thread, especially for high-resolution images. Spawning too many parallel encoding jobs on constrained CI runners (such as GitHub Actions or GitLab Runners with 4GB–7GB of RAM) causes the kernel Out-Of-Memory killer to abruptly terminate the process.
• The Fix: Explicitly limit the concurrency based on the available RAM of your runner tier rather than simply matching virtual CPU cores. As a general rule, reserve at least 1GB to 1.5GB of RAM per concurrent conversion worker.

4. Stripping Essential Color Profiles (ICC)

Automated optimization scripts often include flags to strip all metadata to shave off extra kilobytes.

• The Problem: Stripping color management data can inadvertently discard embedded ICC profiles or color space tags. Because AVIF defaults to Rec. 709 or sRGB when unspecified, wide-gamut (Display P3) source images will appear washed out, overly saturated, or visually altered in modern browsers.
• The Fix: Configure your pipeline tool (e.g., Sharp, ImageMagick, or Squoosh) to retain essential color space metadata or normalize all source assets to sRGB prior to AVIF encoding.

5. Failing to Generate Fallback Formats

While AVIF support across modern browsers is strong, legacy environments, older email clients, web crawlers, and third-party consumers may not support it.

• The Problem: Replacing source images entirely with .avif extensions breaks compatibility for a subset of users.
• The Fix: Ensure your pipeline creates dual or triple outputs (e.g., AVIF alongside WebP and optimized JPEG). Combine this with HTML <picture> elements with appropriate type attributes, or use an edge CDN configured for dynamic content negotiation via the HTTP Accept header.

6. Over-Compressing Low-Complexity Images

AVIF is exceptionally good at preserving details in gradients and complex textures without introducing blocky artifacts, but it can aggressively smooth out high-frequency noise (like film grain) or introduce blur at low quality targets.

• The Problem: Applying a blanket low-quality setting (e.g., quality: 50) across an entire asset directory may produce excellent results for photographs but cause blurriness or smearing on diagrams, line art, or screenshots with text.
• The Fix: Segment your image processing rules. Use higher quality thresholds or lossy-to-lossless settings for graphics and UI assets, while using moderate compression for photographic media.