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

Error message

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

What it means

Validates the AVIF encoderSpeed trade-off. Must be between 1 and 10 inclusive. The default is 10 (fastest). Lower values produce smaller files at the cost of much longer build times. Note the valid range starts at 1, not 0 — a value of 0 triggers this error because the zero-value check (quality fallback) does not apply to EncoderSpeed.

Solutions

Set imaging.avif.encoderSpeed to a value between 1 and 10. Stick with the default 10 unless you have a specific reason.
If you need smaller AVIF files, lower the value gradually (try 8, then 6) and monitor build time — values below 5 are very slow.
If you accidentally set it to 0, change it to 10 (the recommended default) or remove the key.

Example fix

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

# after
[imaging.avif]
encoderSpeed = 10

Defensive patterns

Strategy: validation

Validate before calling

// Validate AVIF encoder speed (1-10, default 10)
func validateAvifEncoderSpeed(speed int) error {
    if speed < 1 || speed > 10 {
        return fmt.Errorf("avif encoderSpeed %d out of range [1,10]", speed)
    }
    return nil
}

Prevention

encoderSpeed starts at 1, not 0 — a common off-by-one error.
Keep encoderSpeed at 10 (the default) unless you have measured a specific file-size benefit from lowering it.
Values below 5 can cause CI build timeouts on sites with many images.

When it happens

Trigger: Setting imaging.avif.encoderSpeed in hugo.toml to 0, a negative number, or any value above 10. Unlike quality, there is no 0-means-default fallback for encoderSpeed — it defaults to 10 only when unset (via defaultAvifEncoderSpeed at construction, not in init()).

Common situations: Setting encoderSpeed to 0 thinking it means 'fastest' or 'default'; setting it to 1 for maximum compression and hitting build timeouts; off-by-one confusion with the 0-indexed webp.method range.

Related errors

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

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