imaging.avif.quality must be between 1 and 100 inclusive, go

Error message

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

What it means

AvifConfig.init validates the effective AVIF quality after fallback resolution: an unset (0) value falls back to the global `imaging.quality`, then to 60, so any value reaching the check that is <1 or >100 was explicitly configured out of range. AVIF quality is a 1-100 scale where higher means better fidelity.

Source

Thrown at resources/images/config.go:728

	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

	// Hint about what type of image this is.
	// Valid values are "picture", "photo", "drawing", "icon", or "text".
	// Default is "photo".

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Set `imaging.avif.quality` to an integer between 1 and 100 (default 60).
If you want lossless output, set `imaging.avif.compression = "lossless"` instead of an out-of-range quality.
Delete the key to inherit the global `imaging.quality` or the default of 60.

Example fix

# before
[imaging.avif]
quality = 850
# after
[imaging.avif]
quality = 85

Defensive patterns

Strategy: validation

Validate before calling

if q := cfg.Imaging.AVIF.Quality; q < 1 || q > 100 {
    return fmt.Errorf("avif quality %d out of range [1,100]", q)
}

Prevention

Clamp or reject quality values outside 1–100 before writing config
Don't use 0 to mean 'default' — omit the key instead
Add a CI config-lint step that range-checks imaging.* values

When it happens

Trigger: Configuring `[imaging.avif] quality` (or the global `[imaging] quality`) with a negative number, a value over 100, or a fractional/percent-style value that decodes out of range. Fires at config load time.

Common situations: Using 0-255 or 0.0-1.0 quality scales from other encoders (e.g. cavif, sharp), setting quality = 0 in the global `imaging.quality` expecting "lossless" (0 means unset in the AVIF block but is invalid globally-propagated as-is only if negative/over-100), or typoing an extra digit like 850.

Related errors

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