imaging.avif.compression must be one of lossy or lossless, g

Error message

imaging.avif.compression must be one of lossy or lossless, got %q

What it means

Hugo validates AVIF encoder settings in AvifConfig.init when loading site configuration. The `imaging.avif.compression` value (after lowercasing and falling back to the global `imaging.compression` or the default) must be a key in the compressionMethods set — only "lossy" or "lossless" are supported by the AVIF encoder.

Source

Thrown at resources/images/config.go:725

	if c.Compression == "" {
		c.Compression = defaultCompression
	}
	if c.Quality == 0 {
		c.Quality = 60
	}

	c.Hint = strings.ToLower(c.Hint)
	c.Compression = strings.ToLower(c.Compression)

	if c.Hint != "" && !hints[c.Hint] {
		return fmt.Errorf("imaging.avif.hint must be one of picture, photo, drawing, icon, or text, got %q", c.Hint)
	}
	if c.EncoderSpeed < 1 || c.EncoderSpeed > 10 {
		return fmt.Errorf("imaging.avif.encoderSpeed must be between 1 and 10, got %d", c.EncoderSpeed)
	}

	if c.Compression != "" && !compressionMethods[c.Compression] {
		return fmt.Errorf("imaging.avif.compression must be one of lossy or lossless, got %q", c.Compression)
	}
	if c.Quality < 1 || c.Quality > 100 {
		return fmt.Errorf("imaging.avif.quality must be between 1 and 100 inclusive, got %d", c.Quality)
	}

	return nil
}

// WebpConfig holds WebP-specific encoding configuration.
type WebpConfig struct {
	// Quality setting (1-100). Falls back to the global imaging.quality if unset.
	// Only relevant for lossy encoding.
	Quality int

	// Compression method to use.
	// One of "lossy" or "lossless".
	Compression string

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Set `imaging.avif.compression` (or the inherited global `imaging.compression`) to exactly "lossy" or "lossless" in your site config.
Remove the key entirely to use the default compression.
If you meant to control quality, use `imaging.avif.quality` (1-100) instead.

Example fix

# before (hugo.toml)
[imaging.avif]
compression = "high"
# after
[imaging.avif]
compression = "lossy"
quality = 60

Defensive patterns

Strategy: validation

Validate before calling

valid := map[string]bool{"lossy": true, "lossless": true}
if !valid[strings.ToLower(cfg.Imaging.AVIF.Compression)] {
    return fmt.Errorf("avif compression must be lossy or lossless")
}

Prevention

Set imaging.avif.compression in hugo.toml only to "lossy" or "lossless"
Validate site config with `hugo config` before builds
Keep an enum of allowed values in deployment scripts that generate config

When it happens

Trigger: Setting `[imaging.avif] compression = "something-else"` (or a global `[imaging] compression`) in hugo.toml/config to any string other than lossy/lossless. Fires at config load / site build time, before any image is processed. Note the value inherits from the global `imaging.compression`, so a bad global value also trips this AVIF-specific check.

Common situations: Copying JPEG/PNG-style options like "none", "best", "medium", or numeric compression levels from other tools; typos like "loseless"; setting the global imaging.compression for WebP and not realizing it also applies to AVIF.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/b534f25d3f5e4046.json. Report an issue: GitHub ↗.