{"record":{"id":"a0d6c229f5d494a4","repo":"gohugoio/hugo","slug":"failed-to-decode-options-s","errorCode":null,"errorMessage":"failed to decode options: %s","messagePattern":"failed to decode options: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/images/filters.go","lineNumber":219,"sourceCode":"}\n\n// Dither creates a filter that dithers an image.\nfunc (*Filters) Dither(options ...any) gift.Filter {\n\tditherOptions := struct {\n\t\tColors     []any\n\t\tMethod     string\n\t\tSerpentine bool\n\t\tStrength   float32\n\t}{\n\t\tMethod:     \"floydsteinberg\",\n\t\tSerpentine: true,\n\t\tStrength:   1.0,\n\t}\n\n\tif len(options) != 0 {\n\t\terr := mapstructure.WeakDecode(options[0], &ditherOptions)\n\t\tif err != nil {\n\t\t\tpanic(fmt.Sprintf(\"failed to decode options: %s\", err))\n\t\t}\n\t}\n\n\tif len(ditherOptions.Colors) == 0 {\n\t\tditherOptions.Colors = []any{\"000000ff\", \"ffffffff\"}\n\t}\n\n\tif len(ditherOptions.Colors) < 2 {\n\t\tpanic(\"palette must have at least two colors\")\n\t}\n\n\tvar palette []color.Color\n\tfor _, c := range ditherOptions.Colors {\n\t\tcc, ok, err := toColorGo(c)\n\t\tif !ok || err != nil {\n\t\t\tpanic(fmt.Sprintf(\"%q is an invalid color: specify RGB or RGBA using hexadecimal notation\", c))\n\t\t}\n\t\tpalette = append(palette, cc)","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/images/filters.go#L201-L237","documentation":"Thrown by images.Dither when mapstructure.WeakDecode fails to decode the options argument into the dither options struct (filters.go:217-220). This happens when the options map contains fields of incompatible types that cannot be weakly coerced.","triggerScenarios":"Passing a Dither options map where Colors is not a list, Method/Serpentine/Strength are the wrong scalar types, or unknown nested structures. WeakDecode tolerates numeric/string coercion but rejects structural mismatches.","commonSituations":"Passing Colors as a single string instead of a slice; passing Strength as a map; or passing a struct where a map is expected.","solutions":["Provide a flat map with keys Colors ([]string), Method (string), Serpentine (bool), Strength (float).","Ensure Colors is always a list even with one entry.","Remove unrecognized/struct-valued keys."],"exampleFix":"// before\n{{ $filters = $filters | append (images.Dither (dict \"Colors\" \"000000ff\")) }}\n// after\n{{ $filters = $filters | append (images.Dither (dict \"Colors\" (slice \"000000ff\" \"ffffffff\"))) }}","handlingStrategy":"validation","validationCode":"{{ $opts := .opts }}\n{{ if and (isset $opts \"Colors\") (not (reflect.IsSlice (index $opts \"Colors\"))) }}\n  {{ errorf \"Dither Colors must be a slice\" }}\n{{ end }}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass Dither options as a flat dict matching the documented keys/types.","Keep Colors a slice of hex strings.","Avoid nesting structs inside the options map."],"tags":["image-filter","dither","validation","hugo"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}