getzola/zola · error

Invalid image format: {}

Error message

Invalid image format: {}

What it means

`Format::from_args` parses a user-supplied format string (e.g. from imageproc config) into the `Format` enum. The match only accepts recognized formats such as `avif`; any other string falls into the catch-all `_` arm and produces this anyhow error. It is a configuration/parsing validation error, not a runtime image decoding failure.

Source

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

                    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",
            Jpeg { .. } => "jpg",
            WebP { .. } => "webp",
            Avif { .. } => "avif",
        }
    }
}

#[allow(clippy::derived_hash_with_manual_eq)]
impl Hash for Format {

View on GitHub (pinned to 61d3082821)

Solutions

1. Check the format string against the exact variants accepted by the `match` in `Format::from_args` (jpeg, png, webp, avif, bmp, etc.) and fix the spelling/case
2. Trim whitespace and lowercase the input before passing it in
3. Update the zola/imageproc version docs to confirm which formats the installed version supports

Example fix

// before (config)
format = "jpg"
// after
format = "jpeg"

const FORMATS: [&str; 6] = ["jpeg", "png", "webp", "avif", "bmp", "tiff"];
fn is_valid_format(f: &str) -> bool {
    FORMATS.contains(&f.trim().to_ascii_lowercase().as_str())
}
if !is_valid_format(cfg.format) { eprintln!("unsupported format: {}", cfg.format); }

fn is_supported_format(f: &str) -> bool {
    matches!(f.trim().to_ascii_lowercase().as_str(), "jpeg" | "png" | "webp" | "avif" | "bmp" | "tiff")
}

match Format::from_args(&raw) {
    Ok(f) => process(f),
    Err(e) if e.to_string().starts_with("Invalid image format") => {
        log::error!("config format rejected: {e}; use one of jpeg/png/webp/avif/bmp/tiff");
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Calling `Format::from_args` with a format string that is not one of the supported enum variants (e.g. a typo like "jpg" vs "jpeg", or "webp" misspelled), typically via the `[imageproc]` settings or an image resize URL/config.

Common situations: Typos in zola config.toml image processing settings; copy-pasting format names from other tools (e.g. 'jpg' when the code expects 'jpeg'); passing an uppercase or whitespace-padded format string that is not normalized before matching.

Related errors

• op="fit_width" requires a `width` argument
• op="fit_height" requires a `height` argument
• op={} requires a `width` and `height` argument
• Invalid image resize operation: {}
• Theme `{}` is missing a templates folder

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