gohugoio/hugo · error

media type not found

Error message

media type %q not found

What it means

Thrown in the mapstructure decode hook (output/config.go:120) when a custom output format's 'mediaType' string does not match any media type registered in Hugo's media.Types. Hugo looks up the type with mediaTypes.GetByType(vviv) and, on miss, returns this error. The mediaType must be a fully-qualified type/subtype (e.g. text/html) that exists in the [mediaTypes] config or the built-in defaults.

Solutions

  1. Add the missing [mediaTypes."text/myformat"] section with suffixes and delimiter before referencing it in outputFormats.
  2. Verify the string exactly matches the registered type/subtype (case-insensitive, no stray spaces/semicolons).
  3. Use a built-in media type (text/html, application/json, application/rss+xml, etc.) if a custom one is not needed.
  4. Run hugo config to list resolved mediaTypes and confirm the value exists.

Example fix

# before (referenced but undefined)
[outputFormats.MYFORMAT]
mediaType = "text/myformat"

# after (define the media type)
[mediaTypes."text/myformat"]
suffixes = ["myfmt"]
[outputFormats.MYFORMAT]
mediaType = "text/myformat"
Defensive patterns

Strategy: validation

Validate before calling

// Confirm a mediaType string exists before referencing it in outputFormats.
func mediaTypeExists(types media.Types, mt string) bool {
    _, found := types.GetByType(mt)
    return found
}

Type guard

// A valid mediaType reference is a non-empty string matching a registered type.
func isValidMediaTypeRef(v any, types media.Types) bool {
    s, ok := v.(string)
    if !ok { return false }
    _, found := types.GetByType(s)
    return found
}

Try / catch

if _, found := mediaTypes.GetByType(mt); !found {
    return fmt.Errorf("define [mediaTypes.%q] first", mt)
}

Prevention

When it happens

Trigger: Defining [outputFormats.X] with mediaType = "text/myformat" without a corresponding [mediaTypes."text/myformat"]; a typo like mediaType = "text/html" vs "text/html;" with stray characters; referencing a media type that was removed in a Hugo version upgrade.

Common situations: Adding a custom output format and forgetting to also add the matching [mediaTypes] entry; renaming a media type; upgrading Hugo where a previously built-in media type was dropped; copy-paste typos in the mediaType string.

Related errors

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

Appendix: source

Thrown at output/config.go:120

				for _, key := range dataVal.MapKeys() {
					keyStr, ok := key.Interface().(string)
					if !ok {
						// Not a string key
						continue
					}
					if strings.EqualFold(keyStr, "mediaType") {
						// If mediaType is a string, look it up and replace it
						// in the map.
						vv := dataVal.MapIndex(key)
						vvi := vv.Interface()

						switch vviv := vvi.(type) {
						case media.Type:
						// OK
						case string:
							mediaType, found := mediaTypes.GetByType(vviv)
							if !found {
								return c, fmt.Errorf("media type %q not found", vviv)
							}
							dataVal.SetMapIndex(key, reflect.ValueOf(mediaType))
						default:
							return nil, fmt.Errorf("invalid output format configuration; wrong type for media type, expected string (e.g. text/html), got %T", vvi)
						}
					}
				}
			}
			return c, nil
		},
	}

	decoder, err := mapstructure.NewDecoder(config)
	if err != nil {
		return err
	}

	if err = decoder.Decode(input); err != nil {

View on GitHub (pinned to 52c9bd7908)