gohugoio/hugo · error

failed to resolve media type for suffix

Error message

failed to resolve media type for suffix %q

What it means

Thrown by resolveContentType when neither markup nor mediaType is set in content config, so Hugo falls back to the file extension and calls MarkupToMediaType(ext). If no registered media type matches that suffix (the returned type IsZero), the extension is unknown to Hugo.

Solutions

1. Register the media type for that suffix in your config under [mediaTypes].
2. Rename the content file to a known extension (md, html, org, etc.).
3. Set the 'markup' or 'mediaType' explicitly in front matter / page config to bypass suffix detection.

Example fix

# before: content/myfile.foo
# after (hugo.toml)
[mediaTypes."text/asciidoc"]
suffixes = ["adoc", "asciidoc"]

ext := strings.TrimPrefix(filepath.Ext(filename), ".")
if mt := pagemeta.MarkupToMediaType(ext, mediaTypes); mt.IsZero() {
    return fmt.Errorf("no media type for extension %q", ext)
}

if err := pcfg.SetMetaPreFromMap(ext, fm, logger, conf); err != nil {
    return fmt.Errorf("content type for %s: %w", filename, err)
}

When it happens

Trigger: A content file with an extension Hugo does not recognize (e.g. '.adoc' when asciidoc isn't configured, or a custom '.foo'), or a content adapter whose path has an unknown extension and no markup/mediaType override.

Common situations: Adding a new markup format without registering its media type under [mediaTypes], or renaming content files to non-standard extensions. Common after enabling a new content format or in monorepo setups with unusual extensions.

Related errors

• failed to resolve media type for
• media type not found
• no content renderer found for markup
• cannot use --renderToMemory with --destination
• cardinalityThreshold threshold must be between 0 and 100

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

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