{"id":"d009fbdd44a6afb0","repo":"gohugoio/hugo","slug":"unmarshal-failed-w","errorCode":null,"errorMessage":"unmarshal failed: %w","messagePattern":"unmarshal failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"parser/metadecoders/decoder.go","lineNumber":332,"sourceCode":"\t\tcase *any:\n\t\t\t*v = xmlValue\n\t\t}\n\tcase TOML:\n\t\terr = toml.Unmarshal(data, v)\n\tcase YAML:\n\t\treturn UnmarshalYaml(data, v)\n\tcase CSV:\n\t\treturn d.unmarshalCSV(data, v)\n\n\tdefault:\n\t\treturn fmt.Errorf(\"unmarshal of format %q is not supported\", f)\n\t}\n\n\tif err == nil {\n\t\treturn nil\n\t}\n\n\treturn toFileError(f, data, fmt.Errorf(\"unmarshal failed: %w\", err))\n}\n\nfunc (d Decoder) unmarshalCSV(data []byte, v any) error {\n\tr := csv.NewReader(bytes.NewReader(data))\n\tr.Comma = d.Delimiter\n\tr.Comment = d.Comment\n\tr.LazyQuotes = d.LazyQuotes\n\n\trecords, err := r.ReadAll()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tswitch vv := v.(type) {\n\tcase *any:\n\t\tswitch d.TargetType {\n\t\tcase \"map\":\n\t\t\tif len(records) < 2 {","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/parser/metadecoders/decoder.go#L314-L350","documentation":"This is the generic wrapper Hugo applies (via toFileError) when the format-specific decoder — json.Unmarshal, toml.Unmarshal, org, or the XML mapper — returns an error in UnmarshalTo. It means the format was recognized but the content is not valid for that format, and the wrapped %w preserves the underlying parser error with file position info where available.","triggerScenarios":"Unmarshal of a data file, front matter, or transform.Unmarshal input whose bytes fail the underlying parser: malformed JSON (trailing commas, comments), invalid TOML (bad dates, duplicate keys), broken XML, or org-mode parse failures. YAML and CSV have their own paths, so this branch mostly surfaces JSON/TOML/XML/ORG syntax errors.","commonSituations":"Hand-edited data/*.json files with trailing commas or comments; TOML front matter with unquoted strings or duplicate keys; remote API responses that return an HTML error page while claiming JSON; merge-conflict markers left in data files; smart quotes pasted from a document into TOML.","solutions":["Read the wrapped error — it names the format and usually the line/column — and fix the syntax at that position in the named file.","Validate the file with an external linter (jq for JSON, a TOML/XML validator) to pinpoint the malformed construct.","For remote resources, verify the response body actually is the expected format (check for HTML error pages, rate-limit responses) before unmarshalling."],"exampleFix":"// before (data/authors.json)\n{\n  \"name\": \"Jane\", // primary author\n}\n// after\n{\n  \"name\": \"Jane\"\n}","handlingStrategy":"try-catch","validationCode":"// cheap syntactic pre-check for JSON input\nif format == metadecoders.JSON && !json.Valid(data) {\n    return errors.New(\"invalid JSON input\")\n}","typeGuard":null,"tryCatchPattern":"if err := decoder.UnmarshalTo(data, format, &v); err != nil {\n    var typeErr *json.UnmarshalTypeError\n    if errors.As(err, &typeErr) {\n        // target type mismatch — fix the destination struct\n    }\n    // otherwise the source document is malformed; report file + err\n    return fmt.Errorf(\"decode %s: %w\", filename, err)\n}","preventionTips":["Treat this as a wrapped error: use errors.As/errors.Is on the unwrapped cause to distinguish syntax errors from type mismatches","Lint data files (yamllint, jq, taplo) in CI before Hugo consumes them","Make sure the destination type matches the document shape (map vs slice vs struct)"],"tags":["hugo","unmarshal","syntax-error","json","toml","xml"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}