{"record":{"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/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/tpl/transform/unmarshal.go#L126-L162","documentation":"The transform.Unmarshal template function can auto-detect the data format (JSON, TOML, YAML, CSV) of a plain string argument. When detection fails and no explicit format was given in the options map, decoder.FormatFromContentString returns an empty metadecoders.Format and this error is raised (unmarshal.go:144). This only applies to the plain-string code path; when a Resource is passed, the MIME-type path is used instead.","triggerScenarios":"Calling {{ transform.Unmarshal $data }} where $data is a string that is not recognizable as JSON/TOML/YAML/CSV, and no options map (e.g. (dict \"format\" \"yaml\")) is supplied as the first argument.","commonSituations":"Passing malformed or structurally ambiguous data to Unmarshal; feeding plain prose text; data whose first characters don't match any known format signature; forgetting to prefix JSON with '{' or '['.","solutions":["Pass an options map specifying the format explicitly: {{ transform.Unmarshal (dict \"format\" \"yaml\") $data }}","Fix the input string so it is valid JSON/TOML/YAML/CSV so auto-detection succeeds","If the source is a Resource, pass the Resource directly so MIME-based detection is used instead of content sniffing"],"exampleFix":"// before\n{{ $v := transform.Unmarshal $someText }}\n// after\n{{ $v := transform.Unmarshal (dict \"format\" \"json\") $someText }}","handlingStrategy":"validation","validationCode":"// Detect format explicitly before calling Unmarshal to avoid the 'unknown format' error.\nfunc detectFormat(s string) (string, bool) {\n    s = strings.TrimSpace(s)\n    switch {\n    case strings.HasPrefix(s, \"{\") || strings.HasPrefix(s, \"[\"):\n        return \"json\", true\n    case strings.HasPrefix(s, \"+++\"):\n        return \"toml\", true\n    case strings.Contains(s, \":\") && !strings.HasPrefix(s, \"<\"):\n        return \"yaml\", true\n    case strings.Contains(s, \",\"):\n        return \"csv\", true\n    }\n    return \"\", false\n}","typeGuard":null,"tryCatchPattern":"{{ with transform.Unmarshal $data }}{{ . }}{{ else }}{{ warnf \"unmarshal failed\" }}{{ end }}","preventionTips":["Always pass an options map with an explicit 'format' key when the input type is known","Validate or sanitize input strings before feeding them to transform.Unmarshal","Prefer passing a Resource object so MIME-type detection is used instead of content sniffing"],"tags":["transform","unmarshal","template","format-detection","hugo"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}