gohugoio/hugo · error

format %q not supported

Error message

format %q not supported

What it means

When transform.Unmarshal receives a Resource and an explicit decoder.Format option, it converts the format string to a metadecoders.Format via FormatFromString (unmarshal.go:76-80). Supported formats are org, json, toml, yaml/yml, csv, xml (format.go:26-32, 52-63). If the provided format string doesn't map to any known format, FormatFromString returns empty and Hugo reports 'format %q not supported'.

Source

Thrown at tpl/transform/unmarshal.go:79

	}

	if r, ok := data.(resource.UnmarshableResource); ok {
		key := r.Key()

		if key == "" {
			return nil, errors.New("no Key set in Resource")
		}

		if decoder != metadecoders.Default {
			key += decoder.OptionsKey()
		}

		v, err := ns.cacheUnmarshal.GetOrCreate(key, func(string) (*resources.StaleValue[any], error) {
			var f metadecoders.Format
			if decoder.Format != "" {
				f = metadecoders.FormatFromString(decoder.Format)
				if f == "" {
					return nil, fmt.Errorf("format %q not supported", decoder.Format)
				}
			} else {
				f = metadecoders.FormatFromStrings(r.MediaType().Suffixes()...)
				if f == "" {
					return nil, fmt.Errorf("MIME %q not supported", r.MediaType())
				}
			}

			reader, err := r.ReadSeekCloser()
			if err != nil {
				return nil, err
			}
			defer reader.Close()

			b, err := io.ReadAll(reader)
			if err != nil {
				return nil, err
			}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Use one of the supported formats: json, yaml, yml, toml, csv, xml, org.
2. If you omitted the format option, Hugo infers from the resource MediaType instead (see MIME error).
3. Pre-convert unsupported formats (e.g. INI) to YAML/JSON with an external tool.

Example fix

// before
{{ transform.Unmarshal (dict "format" "ini") $res }}

// after
{{ transform.Unmarshal (dict "format" "yaml") $res }}

// Only use supported formats when passing 'format' to transform.Unmarshal:
//   json, yaml, yml, toml, csv, xml, org
{{ transform.Unmarshal (dict "format" "json") $res }}

// Validate format against the supported set in Go:
func supportedFormat(s string) bool {
    switch strings.ToLower(s) {
    case "json", "yaml", "yml", "toml", "csv", "xml", "org":
        return true
    }
    return false
}

When it happens

Trigger: Calling {{ transform.Unmarshal (dict "format" "ini") $resource }} or any format string other than json/yaml/yml/toml/csv/xml/org against a Resource argument.

Common situations: Requesting INI, properties, or another format Hugo doesn't support; typo in the format name (e.g. 'yam' instead of 'yaml'); assuming a format is supported because it appears in front matter elsewhere.

Related errors

• MIME %q not supported
• unknown format
• invalid strict mode; expected one of error, ignore, or warn;
• failed to decode options: %w
• type %T not supported

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/c05d9e813b42c25a. Report an issue: GitHub.