gohugoio/hugo · error

imaging.avif.hint must be one of picture, photo, drawing, ic

Error message

imaging.avif.hint must be one of picture, photo, drawing, icon, or text, got %q

What it means

AvifConfig.init validates the AVIF encoder hint, which controls chroma subsampling. The hint (explicit imaging.avif.hint, inherited from imaging.hint, or the default 'photo') is lowercased and checked against the fixed set picture/photo/drawing/icon/text.

Source

Thrown at resources/images/config.go:718

	}
	if c.Quality == 0 {
		c.Quality = ic.Quality
	}
	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.

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Change imaging.avif.hint to one of: picture, photo, drawing, icon, text.
2. Remove the setting to use the default of 'photo'.
3. If the invalid value comes from the global imaging.hint, fix it there since AVIF inherits it.

Example fix

# before (hugo.toml)
[imaging.avif]
hint = "graphic"
# after
[imaging.avif]
hint = "drawing"

switch cfg.Imaging.AVIF.Hint {
case "", "picture", "photo", "drawing", "icon", "text":
default:
    return fmt.Errorf("invalid imaging.avif.hint %q", cfg.Imaging.AVIF.Hint)
}

When it happens

Trigger: Setting imaging.avif.hint (or the global imaging.hint, which AVIF inherits) in site config to any value outside {picture, photo, drawing, icon, text} — e.g. 'image', 'graphic', 'screenshot'. Fires at config load.

Common situations: Guessing hint names from other encoders (cwebp uses different preset names like 'default'); typos ('phot'); using WebP preset values for the AVIF config.

Related errors

• imaging.avif.encoderSpeed must be between 1 and 10, got %d
• imaging.quality must be between 1 and 100 inclusive, got %d
• imaging.jpeg.quality must be between 1 and 100 inclusive, go
• redirects must have either From or FromRe set
• failed to create config from result: %w

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