gohugoio/hugo · error

unknown media type

Error message

unknown media type %q

What it means

Returned by DecodeContentTypes when a key in the [mediaTypes]-derived content types map does not resolve to any known media type via types.GetByType(k). Hugo requires every content type referenced to exist in the decoded media Types set; an unknown type cannot be associated with content handling.

Solutions

1. Add the missing media type under [mediaTypes] with the same key that appears in the content types config.
2. Fix typos: the key must be exactly MainType/SubType (e.g. 'text/markdown').
3. If the content type is no longer needed, remove it from the content types config.

Example fix

# before: content type referenced but media type missing
[outputFormats.MyFormat]
mediaType = "text/myfmt"
# no [mediaTypes] entry

# after
[mediaTypes]
[mediaTypes."text/myfmt"]
suffixes = ["myfmt"]

// Ensure each content type key resolves before decoding.
func validateContentKeys(in map[string]any, known media.Types) error {
    for k := range in {
        if _, ok := known.GetByType(k); !ok {
            return fmt.Errorf("content type %q is not a declared media type", k)
        }
    }
    return nil
}

_, err := media.DecodeContentTypes(in, types)
if err != nil && strings.Contains(err.Error(), "unknown media type") {
    // point user to the missing [mediaTypes] entry
}

When it happens

Trigger: Listing a content type key (a MIME like 'text/myext' or a sub-type) under the content types config that is not declared in the media types config. Fires during media.DecodeContentTypes at startup.

Common situations: Defining a custom output format / content type but forgetting to also declare it under [mediaTypes]; typo in the MIME string; renaming a media type in [mediaTypes] but not updating the content types reference; copy-pasting a format config that assumes a media type that was removed.

Related errors

• failed to decode media types
• cannot parse as a media type
• config needs a filename
• empty related config provided
• failed to decode languages config

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

Appendix: 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 52c9bd7908)