imaging.avif.compression must be one of lossy or lossless…

Error message

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

What it means

Validates the AVIF compression method after lowercasing and fallback. Must be either 'lossy' or 'lossless' (defined in the compressionMethods map). If unset, it inherits the global compression, then defaults to 'lossy'. Only checked when compression is non-empty after resolution.

Solutions

Set imaging.avif.compression to either 'lossy' or 'lossless'.
Omit the key to use the default 'lossy', which is best for photographs.
Use 'lossless' only for images where pixel-perfect reproduction matters (screenshots, diagrams) — it produces significantly larger files.

Example fix

# before (hugo.toml)
[imaging.avif]
compression = "losless"

# after
[imaging.avif]
compression = "lossless"

Defensive patterns

Strategy: validation

Validate before calling

// Validate AVIF compression
func validateAvifCompression(c string) error {
    c = strings.ToLower(c)
    if c != "" && c != "lossy" && c != "lossless" {
        return fmt.Errorf("invalid avif compression %q; valid: lossy, lossless", c)
    }
    return nil
}

Prevention

Use 'lossy' for photographs (dramatically smaller files).
Use 'lossless' only for screenshots, diagrams, or logos with sharp edges.
Double-check spelling: 'lossless' has two s's in each half.

When it happens

Trigger: Setting imaging.avif.compression (or the global imaging.compression) to any string other than lossy or lossless. Case-insensitive after normalization.

Common situations: Typing 'losless' (missing an s), 'loss-less', 'high', or 'max'; confusing compression with quality.

Related errors

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/b534f25d3f5e4046. Report an issue: GitHub.

Appendix: 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 52c9bd7908)