{"id":"aad5b00f5a7f9238","repo":"gohugoio/hugo","slug":"q-is-not-a-valid-configuration-format","errorCode":null,"errorMessage":"%q is not a valid configuration format","messagePattern":"%q is not a valid configuration format","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"parser/metadecoders/decoder.go","lineNumber":106,"sourceCode":"\n\tif m == nil {\n\t\t// We migrated to github.com/goccy/go-yaml in v0.152.0,\n\t\t// which produces nil maps for empty YAML files (and empty map nodes), unlike gopkg.in/yaml.v2.\n\t\t//\n\t\t// To prevent crashes when trying to handle empty config files etc., we ensure we always return a non-nil map here.\n\t\t// See issue 14074.\n\t\tm = make(map[string]any)\n\t}\n\n\treturn m, err\n}\n\n// UnmarshalFileToMap is the same as UnmarshalToMap, but reads the data from\n// the given filename.\nfunc (d Decoder) UnmarshalFileToMap(fs afero.Fs, filename string) (map[string]any, error) {\n\tformat := FormatFromString(filename)\n\tif format == \"\" {\n\t\treturn nil, fmt.Errorf(\"%q is not a valid configuration format\", filename)\n\t}\n\n\tdata, err := afero.ReadFile(fs, filename)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn d.UnmarshalToMap(data, format)\n}\n\n// UnmarshalStringTo tries to unmarshal data to a new instance of type typ.\nfunc (d Decoder) UnmarshalStringTo(data string, typ any) (any, error) {\n\tdata = strings.TrimSpace(data)\n\t// We only check for the possible types in YAML, JSON and TOML.\n\tswitch typ.(type) {\n\tcase string:\n\t\treturn data, nil\n\tcase map[string]any, hmaps.Params:\n\t\tformat := d.FormatFromContentString(data)","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/parser/metadecoders/decoder.go#L88-L124","documentation":"Decoder.UnmarshalFileToMap derives the data format from the filename's extension via FormatFromString; if the extension doesn't map to a known format (toml, yaml/yml, json, xml, csv, org), it returns this error rather than guessing. Hugo refuses to parse configuration/data files whose format it cannot identify.","triggerScenarios":"Passing a filename with an unrecognized or missing extension to UnmarshalFileToMap — e.g. loading a config or theme config named `config.txt`, `hugo.conf`, `config` (no extension), or a data/config file with a typoed extension like `.ymal` or `.jsn`.","commonSituations":"Renaming `hugo.toml` to something nonstandard; editors saving `config.toml.bak` or `hugo.yaml.txt`; migrating from another SSG whose config file has a different extension; scripts generating config files without extensions.","solutions":["Rename the file so its extension matches its actual format: `.toml`, `.yaml`/`.yml`, `.json`, `.xml`, or `.org` (e.g. `hugo.toml`, `config/_default/params.yaml`).","Fix typoed extensions (`.ymal` → `.yaml`, `.jsn` → `.json`).","If the content is in one format but the extension says otherwise, convert the content or the extension so they agree — Hugo dispatches the parser purely on the extension."],"exampleFix":"# before\nconfig/_default/params.ymal\n\n# after\nconfig/_default/params.yaml","handlingStrategy":"validation","validationCode":"var supported = map[string]bool{\".toml\": true, \".yaml\": true, \".yml\": true, \".json\": true, \".xml\": true, \".csv\": true, \".org\": true}\nfunc canDecode(filename string) bool { return supported[strings.ToLower(filepath.Ext(filename))] }","typeGuard":"func isKnownFormat(f metadecoders.Format) bool { return f != \"\" } // FormatFromString returns \"\" for unknown","tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"not a valid configuration format\") {\n    // report the file's extension; rename or convert to toml/yaml/json\n}","preventionTips":["Check the file extension against supported formats (toml/yaml/json/xml/csv/org) before calling transform.Unmarshal or Decode","Don't feed extension-less or misnamed files to data-driven templates; pass the format explicitly where the API allows","Validate CMS/import pipelines emit correct extensions"],"tags":["hugo","config","file-format","parsing"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}