gohugoio/hugo · error

media type %q not found

Error message

media type %q not found

What it means

Raised by `ResourceConfig.Compile` in resources/page/pagemeta/page_frontmatter.go when a page resource declares `content.mediaType` in front matter but that type is not registered in Hugo's media type table (`mediaTypes.GetByType`). Hugo needs a resolved media type to know how to treat the inline content, so it fails the build rather than guessing. The lookup accepts a full type string (e.g. `text/markdown`) or a registered suffix alias.

Source

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

	return nil
}

func (rc *ResourceConfig) Compile(basePath string, fim hugofs.FileMetaInfo, conf config.AllProvider, mediaTypes media.Types) error {
	if rc.Params != nil {
		hmaps.PrepareParams(rc.Params)
	}

	// Note that NormalizePathStringBasic will make sure that we don't preserve the unnormalized path.
	// We do that when we create resources 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.
	rc.Path = paths.NormalizePathStringBasic(path.Join(basePath, rc.Path))
	rc.PathInfo = conf.PathParser().Parse(files.ComponentFolderContent, rc.Path)
	if rc.Content.MediaType != "" {
		var found bool
		rc.ContentMediaType, found = mediaTypes.GetByType(rc.Content.MediaType)
		if !found {
			return fmt.Errorf("media type %q not found", rc.Content.MediaType)
		}
	}

	var sitesMatrixFile sitesmatrix.VectorStore
	if fim != nil {
		sitesMatrixFile = fim.Meta().SitesMatrix
	}

	rc.SitesMatrix = buildSitesMatrixFromSitesConfig(
		conf,
		sitesMatrixFile,
		rc.Sites,
	)

	rc.SitesComplements = buildSitesComplementsFromSitesConfig(
		conf,
		fim.Meta(),
		rc.Sites,

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Correct the `content.mediaType` value in the page's front matter to a full registered type string, e.g. `text/markdown` or `text/html`.
2. Run `hugo config mediatypes` (or `hugo config`) to list every registered type and copy the exact string.
3. If you need a custom type, register it under `[mediaTypes."your/type"]` in hugo.toml with a `suffixes` entry, and confirm it's in the config for the environment you're building.
4. Verify the custom type isn't defined only in a module/theme config that is excluded by your current `--environment` or module mounts.

Example fix

# before — hugo.toml page front matter
resources:
  - name: intro
    content:
      mediaType: markdown
      value: "# Hello"

# after
resources:
  - name: intro
    content:
      mediaType: text/markdown
      value: "# Hello"

// verify media type is registered before referencing it in front matter config
if _, found := conf.MediaTypes.GetByType("text/custom"); !found {
    return fmt.Errorf("media type not registered; add it under [mediaTypes] in site config")
}

When it happens

Trigger: Defining a page resource in front matter via `resources:` with `content: {mediaType: "...", value: "..."}` where the mediaType string is misspelled, uses a vendor type Hugo does not ship, or is a bare extension like `md` rather than `text/markdown`; also hit from `hugolib` page-builder tests that construct ResourceConfig programmatically.

Common situations: Config mistakes such as `mediaType: markdown` or `text/mardown`; relying on a custom type declared under `[mediaTypes]` in a config file that isn't loaded for the active environment/module; upgrading Hugo after a media-type rename so an older front matter value no longer resolves.

Related errors

• content source: failed to convert %T to string: %s
• key %q not allowed in cascade config
• failed to create resource for path %q, expected a resource.R
• failed to decode build config in front matter: %s%s
• failed to decode sitemap config in front matter: %s

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