imaging.webp.quality must be between 1 and 100 inclusive…

Error message

imaging.webp.quality must be between 1 and 100 inclusive, got %d

What it means

Validates the WebP quality after fallback resolution. If imaging.webp.quality is 0, it inherits the global imaging.quality; if that is also 0, it defaults to 75. Only relevant for lossy encoding. After resolution, quality must be 1-100 inclusive.

Solutions

Set imaging.webp.quality to a value between 1 and 100 (typical web: 70-85 for lossy).
If using lossless compression, you can omit quality since it has no effect.
Omit the key to use the default 75.

Example fix

# before (hugo.toml)
[imaging.webp]
quality = 150

# after
[imaging.webp]
quality = 80

Defensive patterns

Strategy: validation

Validate before calling

// Validate WebP quality (0 = inherit global or default 75)
func validateWebpQuality(q, globalQuality int) error {
    resolved := q
    if resolved == 0 { resolved = globalQuality }
    if resolved == 0 { resolved = 75 }
    if resolved < 1 || resolved > 100 {
        return fmt.Errorf("webp quality resolves to %d, out of range [1,100]", resolved)
    }
    return nil
}

Prevention

WebP quality only affects lossy encoding — for lossless, omit it.
WebP default quality 75 matches JPEG default — you can use the same value for both.
Omit the key to inherit global quality or use the default.

When it happens

Trigger: Setting [imaging.webp] quality to below 1 or above 100. A value of 0 triggers fallback, not this error. The quality setting is ignored when compression is lossless.

Common situations: Setting quality above 100; setting quality when using lossless compression (no effect, but not an error); using JPEG-quality values without adjustment.

Related errors

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

Appendix: source

Thrown at resources/images/config.go:791

	}
	if c.Quality == 0 {
		c.Quality = 75
	}

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

	if c.Hint != "" && !hints[c.Hint] {
		return fmt.Errorf("imaging.webp.hint must be one of picture, photo, drawing, icon, or text, got %q", c.Hint)
	}
	if c.Method < 0 || c.Method > 6 {
		return fmt.Errorf("imaging.webp.method must be between 0 and 6, got %d", c.Method)
	}
	if c.Compression != "" && !compressionMethods[c.Compression] {
		return fmt.Errorf("imaging.webp.compression must be one of lossy or lossless, got %q", c.Compression)
	}
	if c.Quality < 1 || c.Quality > 100 {
		return fmt.Errorf("imaging.webp.quality must be between 1 and 100 inclusive, got %d", c.Quality)
	}
	return nil
}

View on GitHub (pinned to 52c9bd7908)