gohugoio/hugo · error

imaging.webp.method must be between 0 and 6, got %d

Error message

imaging.webp.method must be between 0 and 6, got %d

What it means

WebpConfig.init validates `imaging.webp.method`, the libwebp quality/speed trade-off knob: 0 is fastest, 6 is slowest with best compression (Hugo defaults to 2). Values outside 0-6 are rejected at config load because the underlying encoder only accepts that range.

Source

Thrown at resources/images/config.go:785

	}
	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 8a468df065)

Solutions

1. Set `imaging.webp.method` to an integer between 0 and 6 (use 6 for smallest files, 0 for fastest builds).
2. Remove the key to use the default of 2.
3. If you were tuning AVIF speed, use `imaging.avif.encoderSpeed` (1-10) instead — the scales differ.

Example fix

# before
[imaging.webp]
method = 9
# after
[imaging.webp]
method = 6

if m := cfg.Imaging.WebP.Method; m < 0 || m > 6 {
    return fmt.Errorf("webp method %d out of range [0,6]", m)
}

When it happens

Trigger: Setting `[imaging.webp] method` in site config to a negative number or anything above 6.

Common situations: Assuming a 1-10 or 0-100 effort scale like other encoders (AVIF's encoderSpeed is 1-10, which invites confusion), or cranking method to 9/10 hoping for smaller files.

Related errors

• imaging.webp.hint must be one of picture, photo, drawing, ic
• imaging.webp.compression must be one of lossy or lossless, g
• imaging.webp.quality must be between 1 and 100 inclusive, go
• invalid anchor value %q in imaging config
• %q is not a valid resample filter

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