Speed for AVIF must be between {} and {} (inclusive); {} is

Error message

Speed for AVIF must be between {} and {} (inclusive); {} is not valid

What it means

Alongside quality, AVIF accepts a `--speed` flag controlling the encoder speed preset. `ImageFormat::from_args` validates it against the inclusive range SPEED_MIN_AVIF..=SPEED_MAX_AVIF; values outside raise this error with the bounds and the offending value.

Source

Thrown at components/imageproc/src/format.rs:73

                    "Quality for WebP must be between {} and {} (inclusive); {} is not valid",
                    QUALITY_MIN_WEBP,
                    QUALITY_MAX_WEBP,
                    invalid_quality
                )),
            },
            "avif" => {
                let q = match quality.unwrap_or(DEFAULT_QUALITY_AVIF) {
                    valid_quality @ QUALITY_MIN_AVIF..=QUALITY_MAX_AVIF => Ok(valid_quality),
                    invalid_quality => Err(anyhow!(
                        "Quality for AVIF must be between {} and {} (inclusive); {} is not valid",
                        QUALITY_MIN_AVIF,
                        QUALITY_MAX_AVIF,
                        invalid_quality
                    )),
                }?;
                let s = match speed.unwrap_or(DEFAULT_SPEED_AVIF) {
                    valid_speed @ SPEED_MIN_AVIF..=SPEED_MAX_AVIF => Ok(valid_speed),
                    invalid_speed => Err(anyhow!(
                        "Speed for AVIF must be between {} and {} (inclusive); {} is not valid",
                        SPEED_MIN_AVIF,
                        SPEED_MAX_AVIF,
                        invalid_speed
                    )),
                }?;
                Ok(Avif { quality: q, speed: s })
            }
            _ => Err(anyhow!("Invalid image format: {}", format)),
        }
    }

    pub fn extension(&self) -> &str {
        // Kept in sync with RESIZED_FILENAME and op_filename
        use Format::*;

        match *self {
            Png => "png",

View on GitHub (pinned to 61d3082821)

Solutions

Use a speed integer within SPEED_MIN_AVIF..=SPEED_MAX_AVIF (see components/imageproc/src/format.rs), typically 1-10
Omit `--speed` to use DEFAULT_SPEED_AVIF
If you wanted to control file size, adjust `--quality` instead of `--speed`

Example fix

// before
$ zola image --format avif --speed 20 in.png out.avif
// after
$ zola image --format avif --speed 6 in.png out.avif

Defensive patterns

Strategy: validation

Validate before calling

let s = speed.unwrap_or(DEFAULT_SPEED_AVIF);
if !(SPEED_MIN_AVIF..=SPEED_MAX_AVIF).contains(&s) {
    return Err(format!("AVIF speed must be {}-{}, got {}", SPEED_MIN_AVIF, SPEED_MAX_AVIF, s));
}

Type guard

fn is_valid_avif_speed(s: i32) -> bool {
    (SPEED_MIN_AVIF..=SPEED_MAX_AVIF).contains(&s)
}

Try / catch

match ImageFormat::from_args("avif", quality, speed) {
    Ok(f) => f,
    Err(e) if e.to_string().contains("Speed for AVIF") => {
        eprintln!("Falling back to default AVIF speed");
        ImageFormat::from_args("avif", quality, None)?
    }
    Err(e) => return Err(e),
}

Prevention

Check SPEED_MIN_AVIF/SPEED_MAX_AVIF constants for the accepted preset range
Omit --speed to use the default preset
Treat speed as an encode-time knob, not a quality knob — use --quality for file size

When it happens

Trigger: Running `zola image --format avif --speed <n>` where n is outside the AVIF speed bounds (commonly 0/1..10 depending on the constants; e.g. `--speed 20`).

Common situations: Confusing rav1e speed presets (0-10) with other encoders' effort levels; typo or doubled digit; copying `--speed` values from ffmpeg's libaom settings that use a different scale.

Related errors

AI-assisted analysis of getzola/zola@61d3082821 (2026-09-03). Data as JSON: /api/errors/907473185d1a509c. Report an issue: GitHub.