What causes "failed to resolve media type for suffix %q" in gohugoio/hugo?

Register the suffix under a media type in site config: [mediaTypes."text/markdown"] suffixes = ["md", "mdx"].

failed to resolve media type for suffix %q

Error message

failed to resolve media type for suffix %q

What it means

When neither markup nor mediaType is set on a page, Hugo infers the content media type from the file suffix (defaulting to "md") via MarkupToMediaType against the configured media types. If the suffix maps to no configured media type, the result is zero and Hugo fails, because it cannot know how to render the content.

Source

Thrown at resources/page/pagemeta/page_frontmatter.go:412

	}

	// Note that NormalizePathStringBasic will make sure that we don't preserve the unnormalized path.
	// We do that when we create pages from the file system; mostly for backward compatibility,
	// but also because people tend to use the filename to name their resources (with spaces and all),
	// and this isn't relevant when creating resources from an API where it's easy to add textual meta data.
	p.Path = paths.NormalizePathStringBasic(p.Path)

	return p.resolveContentType("", mediaTypes)
}

func (p *PageConfigEarly) resolveContentType(ext string, mediaTypes media.Types) error {
	if p.Content.Markup == "" && p.Content.MediaType == "" {
		if ext == "" {
			ext = "md"
		}
		p.ContentMediaType = MarkupToMediaType(ext, mediaTypes)
		if p.ContentMediaType.IsZero() {
			return fmt.Errorf("failed to resolve media type for suffix %q", ext)
		}
	}

	var s string
	if p.ContentMediaType.IsZero() {
		if p.Content.MediaType != "" {
			s = p.Content.MediaType
			p.ContentMediaType, _ = mediaTypes.GetByType(s)
		}

		if p.ContentMediaType.IsZero() && p.Content.Markup != "" {
			s = p.Content.Markup
			p.ContentMediaType = MarkupToMediaType(s, mediaTypes)
		}
	}

	if p.ContentMediaType.IsZero() {
		return fmt.Errorf("failed to resolve media type for %q", s)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Register the suffix under a media type in site config: [mediaTypes."text/markdown"] suffixes = ["md", "mdx"].
Rename the content file to a supported extension (.md, .html, etc.).
If overriding mediaTypes, extend rather than replace the defaults so standard suffixes keep working.

Example fix

# before: custom mediaTypes wiped markdown suffixes
[mediaTypes."text/markdown"]
suffixes = []
# after
[mediaTypes."text/markdown"]
suffixes = ["md", "markdown", "mdx"]

Defensive patterns

Strategy: validation

Validate before calling

# register unknown suffixes in site config before using them
[mediaTypes."text/x-foo"]
suffixes = ["foo"]

Prevention

Use standard content suffixes (.md, .html, .adoc, …) or register custom mediaTypes in config
Check for typos in file extensions and in content-adapter `mediaType`/path suffixes
After adding a custom media type, also map it to an output format if it must render

When it happens

Trigger: resolveContentType called with an extension that no entry in the site's mediaTypes config claims — e.g. a content file with an unregistered extension processed through a content adapter or pages-from-data path, or a stripped-down custom mediaTypes config that removed markdown mappings.

Common situations: Custom [mediaTypes] config overriding defaults and dropping suffixes; content files with unusual extensions (.mdx, .txt variants) expected to render as markdown; typos in suffix lists when defining custom media types.

Related errors

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