gohugoio/hugo · error

unknown media type %q

Error message

unknown media type %q

What it means

When decoding the contentTypes config section, Hugo validates each key against the site's registered media types via types.GetByType. If a key doesn't match any known media type (built-in or user-defined under mediaTypes), decoding aborts with this error. This prevents silently ignoring a content-type configuration that could never take effect.

Source

Thrown at media/config.go:204

		}
		if len(m) == 0 {
			s = defaultContentTypesConfig
		} else {
			s = make(map[string]ContentTypeConfig)
			m = hmaps.CleanConfigStringMap(m)
			for k, v := range m {
				var ctc ContentTypeConfig
				if err := mapstructure.WeakDecode(v, &ctc); err != nil {
					return c, nil, err
				}
				s[k] = ctc
			}
		}

		for k := range s {
			mediaType, found := types.GetByType(k)
			if !found {
				return c, nil, fmt.Errorf("unknown media type %q", k)
			}
			c.types = append(c.types, mediaType)
		}

		c.init(types)

		return c, s, nil
	}

	ns, err := config.DecodeNamespace[map[string]ContentTypeConfig](in, buildConfig)
	if err != nil {
		return nil, fmt.Errorf("failed to decode media types: %w", err)
	}
	return ns, nil
}

// DecodeTypes decodes the given map of media types.
func DecodeTypes(in map[string]any) (*config.ConfigNamespace[map[string]MediaTypeConfig, Types], error) {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Correct the contentTypes key to an exact registered media type string, e.g. 'text/markdown', 'text/asciidoc', 'text/pandoc'.
2. If it's a custom type, declare it under [mediaTypes.'your/type'] first so it's registered before contentTypes is decoded.
3. Run 'hugo config' to inspect the effective mediaTypes list and match your key against it.

Example fix

# before (hugo.toml)
[contentTypes."markdown"]

# after
[contentTypes."text/markdown"]

// Check the media type is registered before referencing it in outputFormats
if _, found := mediaTypesConfig[strings.ToLower(mt)]; !found {
    return fmt.Errorf("media type %q not defined; add it to mediaTypes first", mt)
}

if err := decodeConfig(cfg); err != nil {
    if strings.Contains(err.Error(), "unknown media type") {
        // report which outputFormat references an undefined media type
    }
    return err
}

When it happens

Trigger: A contentTypes map key in site config that is not a registered media type — e.g. [contentTypes.'text/markdown2'] or a key with a typo like 'text/mardown'. Also hit when a custom media type is referenced in contentTypes but was never declared under mediaTypes, so GetByType returns not-found.

Common situations: Typos in contentTypes keys; using a file extension ('md') instead of the MIME string ('text/markdown'); defining contentTypes for a custom type before/without adding it to mediaTypes; copying config between Hugo versions where a built-in type name changed.

Related errors

• target path %q is not a known content format
• cannot parse %q as a media type
• failed to decode media types: %w
• language %q not found
• unsupported format: %q

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