gohugoio/hugo · error

invalid avif config: %w

Error message

invalid avif config: %w

What it means

Wrapper error returned by ImagingConfig.init() when the AVIF sub-configuration (cfg.Avif.init) fails validation. The %w wraps the specific underlying AVIF failure (hint, encoderSpeed, compression, or quality). Runs at startup during the [imaging] namespace decode.

Source

Thrown at resources/images/config.go:574

	"exif": true,
	"iptc": true,
	"xmp":  true,
}

func (cfg *ImagingConfig) init() error {
	cfg.BgColor = strings.ToLower(strings.TrimPrefix(cfg.BgColor, "#"))
	cfg.Anchor = strings.ToLower(cfg.Anchor)
	cfg.ResampleFilter = strings.ToLower(cfg.ResampleFilter)
	cfg.Hint = strings.ToLower(cfg.Hint)
	cfg.Compression = strings.ToLower(cfg.Compression)
	if err := cfg.Jpeg.init(cfg); err != nil {
		return fmt.Errorf("invalid jpeg config: %w", err)
	}
	if err := cfg.Webp.init(cfg); err != nil {
		return fmt.Errorf("invalid webp config: %w", err)
	}
	if err := cfg.Avif.init(cfg); err != nil {
		return fmt.Errorf("invalid avif config: %w", err)
	}
	if cfg.Quality < 0 || cfg.Quality > 100 {
		return fmt.Errorf("imaging.quality must be between 1 and 100 inclusive, got %d", cfg.Quality)
	}

	if cfg.Anchor == "" {
		cfg.Anchor = smartCropIdentifier
	}

	if strings.TrimSpace(cfg.Exif.IncludeFields) == "" && strings.TrimSpace(cfg.Exif.ExcludeFields) == "" {
		// Don't change this for no good reason. Please don't.
		cfg.Exif.ExcludeFields = "GPS|Exif|Exposure[M|P|B]|Contrast|Resolution|Sharp|JPEG|Metering|Sensing|Saturation|ColorSpace|Flash|WhiteBalance"
	}

	if len(cfg.Meta.Fields) == 0 {
		// Default: include all fields except technical metadata.
		// Don't change this for no good reason. Please don't.
		cfg.Meta.Fields = []string{

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Inspect the wrapped error for the exact AVIF field that failed and its allowed range.
2. Fix [imaging.avif] in hugo.toml: hint ∈ {picture,photo,drawing,icon,text}, encoderSpeed ∈ [1,10], compression ∈ {lossy,lossless}, quality ∈ [1,100].
3. Remove the [imaging.avif] section entirely to use the defaults (lossy, photo hint, encoderSpeed 10, quality 60).

Example fix

# before (hugo.toml)
[imaging.avif]
quality = 50
encoderSpeed = 0
hint = "photograph"

# after
[imaging.avif]
quality = 50
encoderSpeed = 1
hint = "photo"

// Validate AVIF config before calling init()
func validateAvifConfig(a AvifConfig, globalQuality int) error {
    validHints := map[string]bool{"picture":true,"photo":true,"drawing":true,"icon":true,"text":true}
    h := strings.ToLower(a.Hint)
    if h != "" && !validHints[h] {
        return fmt.Errorf("invalid avif hint %q", h)
    }
    if a.EncoderSpeed < 1 || a.EncoderSpeed > 10 {
        return fmt.Errorf("avif encoderSpeed %d out of range [1,10]", a.EncoderSpeed)
    }
    c := strings.ToLower(a.Compression)
    if c != "" && c != "lossy" && c != "lossless" {
        return fmt.Errorf("invalid avif compression %q", c)
    }
    q := a.Quality; if q == 0 { q = globalQuality }; if q == 0 { q = 60 }
    if q < 1 || q > 100 {
        return fmt.Errorf("avif quality %d out of range [1,100]", q)
    }
    return nil
}

When it happens

Trigger: Setting [imaging.avif] in hugo.toml with an invalid hint, an encoderSpeed outside 1-10, a compression value other than lossy/lossless, or quality outside 1-100. Also triggered by a programmatic ImagingConfig with a bad AvifConfig.

Common situations: Setting encoderSpeed to 0 (the valid floor is 1, not 0); setting encoderSpeed too low (e.g. 1) causing extremely long build times even before hitting this error; typo in compression; confusing quality with encoderSpeed.

Related errors

• imaging.avif.hint must be one of picture, photo, drawing, ic
• imaging.avif.encoderSpeed must be between 1 and 10, got %d
• imaging.avif.compression must be one of lossy or lossless, g
• imaging.avif.quality must be between 1 and 100 inclusive, go
• invalid webp config: %w

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