imaging.avif.encoderSpeed must be between 1 and 10, got %d

Error message

imaging.avif.encoderSpeed must be between 1 and 10, got %d

What it means

imaging.avif.encoderSpeed sets the AVIF encoder's quality/speed trade-off, where 1 is slowest/smallest and 10 is fastest (the default). AvifConfig.init rejects any value outside 1–10 because the underlying encoder only accepts that range. Note that an explicit 0 is out of range here — there is no zero-value fallback for this field.

Source

Thrown at resources/images/config.go:721

	}
	if c.Hint == "" {
		c.Hint = defaultHint
	}
	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

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Set imaging.avif.encoderSpeed to a value between 1 and 10 (default is 10; staying above 5 avoids very long builds).
Remove the setting entirely to use the default.
If you wanted smaller files, use a lower speed like 5–6 rather than 0.

Example fix

# before (hugo.toml)
[imaging.avif]
encoderSpeed = 0
# after
[imaging.avif]
encoderSpeed = 10

Defensive patterns

Strategy: validation

Validate before calling

if s := cfg.Imaging.AVIF.EncoderSpeed; s != 0 && (s < 1 || s > 10) {
    return fmt.Errorf("imaging.avif.encoderSpeed must be 1-10, got %d", s)
}

Prevention

Keep imaging.avif.encoderSpeed within 1–10; don't reuse quality-style 1–100 values here
Note that each numeric imaging option has its own range — check docs per key
Add a config-validation step (hugo build in CI) to catch out-of-range encoder settings early

When it happens

Trigger: Setting imaging.avif.encoderSpeed = 0, 11, or any value outside 1–10 in hugo.toml; also triggered when the field is unset and defaulting fails to apply (e.g. explicitly setting it to 0 thinking that means 'default'). Fires at config load.

Common situations: Assuming 0 means 'use default'; mapping from encoders with different speed scales (e.g. cavif/libaom 0-based speed settings); trying very low values and going negative.

Related errors

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