{"id":"ba4443a32b418857","repo":"gohugoio/hugo","slug":"failed-to-decode-options-w","errorCode":null,"errorMessage":"failed to decode options: %w","messagePattern":"failed to decode options: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/transform/unmarshal.go","lineNumber":59,"sourceCode":"\t}\n\n\tvar data any\n\tdecoder := metadecoders.Default\n\n\tif len(args) == 1 {\n\t\tdata = args[0]\n\t} else {\n\t\tm, ok := args[0].(map[string]any)\n\t\tif !ok {\n\t\t\treturn nil, errors.New(\"first argument must be a map\")\n\t\t}\n\n\t\tvar err error\n\n\t\tdata = args[1]\n\t\tdecoder, err = decodeDecoder(m)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to decode options: %w\", err)\n\t\t}\n\t}\n\n\tif r, ok := data.(resource.UnmarshableResource); ok {\n\t\tkey := r.Key()\n\n\t\tif key == \"\" {\n\t\t\treturn nil, errors.New(\"no Key set in Resource\")\n\t\t}\n\n\t\tif decoder != metadecoders.Default {\n\t\t\tkey += decoder.OptionsKey()\n\t\t}\n\n\t\tv, err := ns.cacheUnmarshal.GetOrCreate(key, func(string) (*resources.StaleValue[any], error) {\n\t\t\tvar f metadecoders.Format\n\t\t\tif decoder.Format != \"\" {\n\t\t\t\tf = metadecoders.FormatFromString(decoder.Format)","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/tpl/transform/unmarshal.go#L41-L77","documentation":"After validating that the first argument is a map, `transform.Unmarshal` decodes it into its decoder options struct (delimiter, comment, format, etc.) via mapstructure. If a key's value can't be converted to the expected type — for example a delimiter that isn't a single character, or a value of the wrong kind — the underlying decode error is wrapped and returned as this error.","triggerScenarios":"`{{ transform.Unmarshal (dict \"delimiter\" \";;\") $csv }}` — CSV delimiter/comment must decode to a single rune; passing a slice or map where a scalar option is expected; option values of incompatible types that mapstructure cannot weakly convert.","commonSituations":"CSV parsing with a multi-character delimiter string; options loaded from site config or front matter with wrong types; typos in values (keys that are unknown are generally ignored — this error is about values that fail to convert).","solutions":["Read the wrapped error text after the prefix — it names the failing option and why.","Ensure `delimiter` and `comment` are single characters, e.g. `(dict \"delimiter\" \";\")`.","Check each option value's type against the docs for transform.Unmarshal (strings for format, single chars for CSV controls, bool for lazyQuotes)."],"exampleFix":"<!-- before -->\n{{ transform.Unmarshal (dict \"delimiter\" \"||\") $csv }}\n<!-- after -->\n{{ transform.Unmarshal (dict \"delimiter\" \"|\") $csv }}","handlingStrategy":"validation","validationCode":"{{/* use only documented option keys, e.g. for CSV: */}}\n{{ $opts := dict \"delimiter\" \";\" \"comment\" \"#\" \"lazyQuotes\" true }}\n{{ $d := unmarshal $opts $csv }}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use only documented option keys with correct types (delimiter/comment are single-char strings, lazyQuotes a bool)","A delimiter longer than one character fails decoding — keep it a single rune","Check the unmarshal docs for the format-specific option set before adding keys"],"tags":["hugo","templates","unmarshal","options","csv"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}