{"id":"f74c921ac4bf8b02","repo":"gohugoio/hugo","slug":"unknown-format","errorCode":null,"errorMessage":"unknown format","messagePattern":"unknown format","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"tpl/transform/unmarshal.go","lineNumber":144,"sourceCode":"\t}\n\n\tkey := hashing.XxHashFromStringHexEncoded(dataStr)\n\n\tif decoder != metadecoders.Default {\n\t\tkey += decoder.OptionsKey()\n\t}\n\n\tv, err := ns.cacheUnmarshal.GetOrCreate(key, func(string) (*resources.StaleValue[any], error) {\n\t\tvar f metadecoders.Format\n\t\tif decoder.Format != \"\" {\n\t\t\tf = metadecoders.FormatFromString(decoder.Format)\n\t\t\tif f == \"\" {\n\t\t\t\treturn nil, fmt.Errorf(\"format %q not supported\", decoder.Format)\n\t\t\t}\n\t\t} else {\n\t\t\tf = decoder.FormatFromContentString(dataStr)\n\t\t\tif f == \"\" {\n\t\t\t\treturn nil, errors.New(\"unknown format\")\n\t\t\t}\n\t\t}\n\n\t\tv, err := decoder.Unmarshal([]byte(dataStr), f)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\n\t\treturn &resources.StaleValue[any]{\n\t\t\tValue: v,\n\t\t\tStaleVersionFunc: func() uint32 {\n\t\t\t\treturn 0\n\t\t\t},\n\t\t}, nil\n\t})\n\tif err != nil {\n\t\treturn nil, err\n\t}","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/tpl/transform/unmarshal.go#L126-L162","documentation":"When `transform.Unmarshal` is given a raw string and no explicit `format` option, Hugo sniffs the content with `decoder.FormatFromContentString` (looking for JSON braces, TOML/YAML markers, etc.). If the sniffer can't classify the string, this generic 'unknown format' error is returned.","triggerScenarios":"`{{ transform.Unmarshal $someString }}` where the string doesn't start with recognizable JSON/TOML/YAML/XML/CSV structure — e.g. plain prose, HTML, an error page body, or an empty-ish/whitespace-padded fragment.","commonSituations":"A remote API call returned an HTML error page or empty body instead of JSON (rate limiting, auth failure) and the body string was piped to unmarshal; unmarshaling CSV without specifying format (CSV can't be sniffed reliably); truncated or corrupted data files.","solutions":["Specify the format explicitly: `transform.Unmarshal (dict \"format\" \"csv\") $str`.","Print/inspect the string first (`{{ warnf \"%s\" $str }}`) — remote fetches often return HTML error bodies; check `.Err` on `resources.GetRemote` before unmarshaling.","Validate the source data is well-formed JSON/TOML/YAML."],"exampleFix":"{{/* before */}}\n{{ $rows := transform.Unmarshal $csvString }}\n{{/* after */}}\n{{ $rows := transform.Unmarshal (dict \"format\" \"csv\") $csvString }}","handlingStrategy":"validation","validationCode":"{{ $s := trim $content \" \\n\\t\" }}\n{{ if or (hasPrefix $s \"{\") (hasPrefix $s \"[\") (hasPrefix $s \"<\") (findRE `^[\\w-]+\\s*[:=]` $s) }}\n  {{ $data := transform.Unmarshal $s }}\n{{ end }}","typeGuard":null,"tryCatchPattern":"{{ with try (transform.Unmarshal $s) }}\n  {{ with .Err }}{{ warnf \"unknown data format, skipping: %s\" . }}{{ else }}{{ $data := .Value }}{{ end }}\n{{ end }}","preventionTips":["Unmarshal from Resources (which carry a media type) rather than raw strings so the format is detected from the MIME type, not sniffed","When unmarshaling a raw string, make sure it is actually well-formed JSON/TOML/YAML/XML/CSV — empty strings and HTML bodies trigger this error","Check remote responses for error pages (HTML) before unmarshaling API results"],"tags":["hugo","templates","unmarshal","format-detection"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}