What causes "unknown format" in gohugoio/hugo?

Pass an options map specifying the format explicitly: {{ transform.Unmarshal (dict "format" "yaml") $data }}

unknown format

Error message

unknown format

What it means

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.

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

Example fix

// before
{{ $v := transform.Unmarshal $someText }}
// after
{{ $v := transform.Unmarshal (dict "format" "json") $someText }}

Defensive patterns

Strategy: validation

Validate before calling

// Detect format explicitly before calling Unmarshal to avoid the 'unknown format' error.
func detectFormat(s string) (string, bool) {
    s = strings.TrimSpace(s)
    switch {
    case strings.HasPrefix(s, "{") || strings.HasPrefix(s, "["):
        return "json", true
    case strings.HasPrefix(s, "+++"):
        return "toml", true
    case strings.Contains(s, ":") && !strings.HasPrefix(s, "<"):
        return "yaml", true
    case strings.Contains(s, ","):
        return "csv", true
    }
    return "", false
}

Try / catch

{{ with transform.Unmarshal $data }}{{ . }}{{ else }}{{ warnf "unmarshal failed" }}{{ end }}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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 '['.

Related errors

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

Appendix: source

Thrown at tpl/transform/unmarshal.go:144

	}

	key := hashing.XxHashFromStringHexEncoded(dataStr)

	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 = decoder.FormatFromContentString(dataStr)
			if f == "" {
				return nil, errors.New("unknown format")
			}
		}

		v, err := decoder.Unmarshal([]byte(dataStr), f)
		if err != nil {
			return nil, err
		}

		return &resources.StaleValue[any]{
			Value: v,
			StaleVersionFunc: func() uint32 {
				return 0
			},
		}, nil
	})
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 52c9bd7908)