gohugoio/hugo · error

unsupported Format provided

Error message

unsupported Format provided

What it means

parser.InterfaceToConfig only knows how to marshal to YAML, TOML, JSON, and XML; any other metadecoders.Format value falls through to this error. It guards against a zero-value or decode-only Format (like CSV or ORG, which Hugo can read but not write here) being used for serialization.

Source

Thrown at parser/frontmatter.go:74

		}

		_, err = w.Write(b)
		if err != nil {
			return err
		}

		_, err = w.Write([]byte{'\n'})
		return err
	case metadecoders.XML:
		b, err := xml.AnyXmlIndent(in, "", "\t", "root")
		if err != nil {
			return err
		}

		_, err = w.Write(b)
		return err
	default:
		return errors.New("unsupported Format provided")
	}
}

func InterfaceToFrontMatter(in any, format metadecoders.Format, w io.Writer) error {
	if in == nil {
		return errors.New("input was nil")
	}

	switch format {
	case metadecoders.YAML:
		_, err := w.Write([]byte(yamlDelimLf))
		if err != nil {
			return err
		}

		err = InterfaceToConfig(in, format, w)
		if err != nil {
			return err

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Use one of the supported output formats: yaml, toml, json, or xml.
2. If resolving the format from a string, check that metadecoders.FormatFromString returned a non-empty Format before calling InterfaceToConfig.
3. For org-mode or CSV targets, convert to a supported format instead — Hugo cannot marshal those.

Example fix

// before
f := metadecoders.FormatFromString(userInput)
err := parser.InterfaceToConfig(v, f, w)
// after
f := metadecoders.FormatFromString(userInput)
if f == "" {
    return fmt.Errorf("unknown format %q; use yaml, toml, json or xml", userInput)
}
err := parser.InterfaceToConfig(v, f, w)

f := metadecoders.FormatFromString(ext)
if f == "" {
    return fmt.Errorf("unknown front matter format for %q", ext)
}

func isFrontMatterFormat(f metadecoders.Format) bool {
    switch f {
    case metadecoders.YAML, metadecoders.TOML, metadecoders.JSON, metadecoders.ORG:
        return true
    }
    return false
}

b, err := parser.InterfaceToFrontMatter(in, format)
if err != nil {
    if strings.Contains(err.Error(), "unsupported Format") {
        // default to YAML or ask the caller for a valid format
    }
    return err
}

When it happens

Trigger: Calling InterfaceToConfig/InterfaceToFrontMatter with a Format that is empty (zero value from FormatFromString on an unknown string) or one without a marshal branch — e.g. metadecoders.CSV or metadecoders.ORG. Reached via `hugo convert` and new-content/archetype code when the target format string doesn't resolve.

Common situations: Passing a mistyped or unsupported format name to `hugo convert` or to front matter output settings (e.g. "yml" handled, but arbitrary strings not); programmatic use where FormatFromString returned "" and the caller didn't check; trying to emit front matter as ORG/CSV, which Hugo only decodes.

Related errors

• input was nil
• unmarshal of format %q is not supported
• failed to create page from file %q: %w
• failed to create page meta from file %q: %w
• language %q not found

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/d646f21c448c0f9b.json. Report an issue: GitHub ↗.