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

Error message

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

What it means

Validates the WebP hint value after lowercasing and fallback resolution. The hint (called 'preset' in libwebp) controls encoding behavior and must be one of: picture, photo, drawing, icon, or text. If unset, it falls back to the global hint, then to the default 'photo'. Only checked when non-empty after resolution.

Solutions

Set imaging.webp.hint to one of: picture, photo, drawing, icon, or text.
Omit the hint to use the default 'photo'.
Check the global imaging.hint if the WebP-specific hint is unset, since WebP inherits it.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

// Validate WebP hint
func validateWebpHint(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 webp hint %q; valid: picture, photo, drawing, icon, text", h)
    }
    return nil
}

Prevention

Omit the hint to use the default 'photo'.
Use 'picture' for images that are a composite of photo and synthetic elements.
The hint and compression settings are independent — set both correctly.

When it happens

Trigger: Setting imaging.webp.hint (or the global imaging.hint) to a string not in the allowed set. Case-insensitive after lowercasing.

Common situations: Typing 'photograph' instead of 'photo'; 'screenshot' instead of 'picture' or 'drawing'; using a hint from a different image library.

Related errors

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

Appendix: source

Thrown at resources/images/config.go:782

	}
	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 = 75
	}

	c.Hint = strings.ToLower(c.Hint)
	c.Compression = strings.ToLower(c.Compression)

	if c.Hint != "" && !hints[c.Hint] {
		return fmt.Errorf("imaging.webp.hint must be one of picture, photo, drawing, icon, or text, got %q", c.Hint)
	}
	if c.Method < 0 || c.Method > 6 {
		return fmt.Errorf("imaging.webp.method must be between 0 and 6, got %d", c.Method)
	}
	if c.Compression != "" && !compressionMethods[c.Compression] {
		return fmt.Errorf("imaging.webp.compression must be one of lossy or lossless, got %q", c.Compression)
	}
	if c.Quality < 1 || c.Quality > 100 {
		return fmt.Errorf("imaging.webp.quality must be between 1 and 100 inclusive, got %d", c.Quality)
	}
	return nil
}

View on GitHub (pinned to 52c9bd7908)