gohugoio/hugo · error

unmarshal of format is not supported

Error message

unmarshal of format %q is not supported

What it means

Thrown by the default branch of Decoder.UnmarshalTo (parser/metadecoders/decoder.go:325) when the Format argument is not one of the supported cases (ORG, JSON, XML, TOML, YAML, CSV). The %q names the unsupported format value. This usually means an empty Format string or a custom/misspelled format was passed.

Solutions

1. Pass one of the six Format constants: metadecoders.YAML, JSON, TOML, ORG, CSV, or XML.
2. If inferring from a filename/content, check FormatFromString/FormatFromContentString returned non-empty before calling UnmarshalTo.
3. Validate the format against the known set in a helper before invoking the decoder.

Example fix

// before
err := dec.UnmarshalTo(data, metadecoders.Format("markdown"), &v)

// after
err := dec.UnmarshalTo(data, metadecoders.YAML, &v)

// Confirm a Format is supported before UnmarshalTo.
func isSupportedFormat(f metadecoders.Format) bool {
    switch f {
    case metadecoders.ORG, metadecoders.JSON, metadecoders.TOML, metadecoders.YAML, metadecoders.CSV, metadecoders.XML:
        return true
    }
    return false
}

if err := dec.UnmarshalTo(data, f, &m); err != nil {
    return fmt.Errorf("unsupported format %q: %w", f, err)
}

When it happens

Trigger: Calling UnmarshalTo with f = "" (empty), f = "html", f = "markdown", or any value outside the six recognized Format constants; FormatFromString returning empty and that empty value being passed through to UnmarshalTo.

Common situations: Programmatic API misuse; inferring a format from a file extension that isn't recognized and forwarding the empty result; a typo in a hard-coded format string.

Related errors

• cannot unmarshal CSV into %T
• cannot unmarshal CSV into %T: invalid targetType: expected…
• invalid targetType: expected either slice or map, received
• is not a valid configuration format
• unmarshal: %T not supported

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

Appendix: source

Thrown at parser/metadecoders/decoder.go:325

			}
			xmlValue = mapValue
		}

		switch v := v.(type) {
		case *map[string]any:
			*v = xmlValue
		case *any:
			*v = xmlValue
		}
	case TOML:
		err = toml.Unmarshal(data, v)
	case YAML:
		return UnmarshalYaml(data, v)
	case CSV:
		return d.unmarshalCSV(data, v)

	default:
		return fmt.Errorf("unmarshal of format %q is not supported", f)
	}

	if err == nil {
		return nil
	}

	return toFileError(f, data, fmt.Errorf("unmarshal failed: %w", err))
}

func (d Decoder) unmarshalCSV(data []byte, v any) error {
	r := csv.NewReader(bytes.NewReader(data))
	r.Comma = d.Delimiter
	r.Comment = d.Comment
	r.LazyQuotes = d.LazyQuotes

	records, err := r.ReadAll()
	if err != nil {
		return err

View on GitHub (pinned to 52c9bd7908)