What causes "imaging.webp.method must be between 0 and 6, got %d" in gohugoio/hugo?

Set imaging.webp.method to a value between 0 and 6. The default 2 is a good balance.

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

Error message

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

What it means

Validates the WebP method (quality/speed trade-off for libwebp). Must be between 0 and 6 inclusive, where 0 is fastest and 6 is slowest with best compression. The default is 2. Note this range is 0-indexed, unlike AVIF's encoderSpeed which starts at 1.

Solutions

Set imaging.webp.method to a value between 0 and 6. The default 2 is a good balance.
Remove the key to use the default method 2.
Only increase to 4-6 if you need the smallest possible WebP files and can tolerate longer builds.

Example fix

# before (hugo.toml)
[imaging.webp]
method = 7

# after
[imaging.webp]
method = 6

Defensive patterns

Strategy: validation

Validate before calling

// Validate WebP method (0-6, default 2)
func validateWebpMethod(method int) error {
    if method < 0 || method > 6 {
        return fmt.Errorf("webp method %d out of range [0,6]", method)
    }
    return nil
}

Prevention

webp.method is 0-indexed (0-6), unlike avif.encoderSpeed which is 1-indexed (1-10).
The default of 2 is a good speed/quality balance — only change if you have measured results.
Method 6 can be 10x slower than method 0 for marginal file size improvement.

When it happens

Trigger: Setting imaging.webp.method in hugo.toml to a negative number or any value above 6. There is no 0-means-default fallback for method — the default of 2 is applied at config construction, not in init().

Common situations: Setting method to 7 (off-by-one from the 0-6 range); confusing this 0-6 scale with AVIF's 1-10 encoderSpeed scale; setting it to 6 for smallest files and experiencing slow builds.

Related errors

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

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