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

Error message

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

What it means

Validates the AVIF hint value after lowercasing and fallback resolution. The hint controls chroma subsampling and must be one of: picture, photo, drawing, icon, or text (defined in the hints map). If unset, it falls back to the global hint, then to the default 'photo'. Only checked when the hint is non-empty after resolution.

Solutions

Set imaging.avif.hint to one of: picture, photo, drawing, icon, or text.
Omit the hint key to use the default 'photo', which is correct for most photographs.
If you set a global imaging.hint, ensure it is also valid since AVIF inherits it when the AVIF-specific hint is unset.

Example fix

# before (hugo.toml)
[imaging.avif]
hint = "photograph"

# after
[imaging.avif]
hint = "photo"

Defensive patterns

Strategy: validation

Validate before calling

// Validate AVIF hint
func validateAvifHint(hint string) error {
    valid := map[string]bool{"picture":true,"photo":true,"drawing":true,"icon":true,"text":true}
    h := strings.ToLower(hint)
    if h != "" && !valid[h] {
        return fmt.Errorf("invalid avif hint %q; valid: picture, photo, drawing, icon, text", h)
    }
    return nil
}

Prevention

Omit the hint to use the default 'photo', which covers most use cases.
Use 'drawing' for line art, 'icon' for small UI graphics, 'text' for images dominated by text.
Remember the hint is shared vocabulary between WebP and AVIF — the same five values apply to both.

When it happens

Trigger: Setting imaging.avif.hint (or the global imaging.hint) to a string that is not picture, photo, drawing, icon, or text. Case does not matter — the value is lowercased before validation.

Common situations: Typing 'photograph' instead of 'photo'; 'graphics' instead of 'drawing'; using a hint name from a different encoder's vocabulary.

Related errors

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

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