gohugoio/hugo · error

%q is an invalid dithering method: see documentation

Error message

%q is an invalid dithering method: see documentation

What it means

Thrown by images.Dither when the Method string matches neither the error-diffusion nor the ordered dithering method maps (filters.go:241-248). Method is lowercased before lookup, so case does not matter, but the spelling must match a known constant.

Source

Thrown at resources/images/filters.go:247

	}

	var palette []color.Color
	for _, c := range ditherOptions.Colors {
		cc, ok, err := toColorGo(c)
		if !ok || err != nil {
			panic(fmt.Sprintf("%q is an invalid color: specify RGB or RGBA using hexadecimal notation", c))
		}
		palette = append(palette, cc)
	}

	d := dither.NewDitherer(palette)
	if method, ok := ditherMethodsErrorDiffusion[strings.ToLower(ditherOptions.Method)]; ok {
		d.Matrix = dither.ErrorDiffusionStrength(method, ditherOptions.Strength)
		d.Serpentine = ditherOptions.Serpentine
	} else if method, ok := ditherMethodsOrdered[strings.ToLower(ditherOptions.Method)]; ok {
		d.Mapper = dither.PixelMapperFromMatrix(method, ditherOptions.Strength)
	} else {
		panic(fmt.Sprintf("%q is an invalid dithering method: see documentation", ditherOptions.Method))
	}

	return filter{
		Options: newFilterOpts(ditherOptions),
		Filter:  ditherFilter{ditherer: d},
	}
}

// AutoOrient creates a filter that rotates and flips an image as needed per
// its EXIF orientation tag.
func (*Filters) AutoOrient() gift.Filter {
	return filter{
		Filter: autoOrientFilter{},
	}
}

// Brightness creates a filter that changes the brightness of an image.
// The percentage parameter must be in range (-100, 100).

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Use a documented method name exactly, e.g. floydsteinberg, atkinson, stucki, sierra, clustereddot4x4.
2. Check dither.go for the authoritative list of accepted keys.
3. Omit Method to use the default (floydsteinberg).

Example fix

// before
{{ $filters = $filters | append (images.Dither (dict "Method" "bayer")) }}
// after
{{ $filters = $filters | append (images.Dither (dict "Method" "floydsteinberg")) }}

{{ $methods := slice "floydsteinberg" "atkinson" "burkes" "stucki" "sierra" "clustereddot4x4" }}
{{ if and (ne .method "") (not (in $methods (lower .method))) }}
  {{ errorf "unknown dither method %q" .method }}
{{ end }}

When it happens

Trigger: Passing Method values like "bayer", "none", "random", or misspelled names such as "floyd-steinberg" (hyphen) or "Sierra2_4A" (the underscore variant is "sierra2_4a").

Common situations: Developer invents a method name, copies a name from a different library, or includes separators/prefixes the map does not use.

Related errors

• failed to decode options: %s
• palette must have at least two colors
• %q is an invalid color: specify RGB or RGBA using hexadecima
• aligny must be one of top, center, bottom
• the padding filter requires between 1 and 5 arguments

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