gohugoio/hugo · error

unknown output format %q for kind %q

Error message

unknown output format %q for kind %q

What it means

In the `outputs` config map, each page kind (home, section, page, taxonomy, term) lists output format names that must exist in Hugo's built-in or custom `outputFormats` definitions. If `outputFormats.GetByName` misses, Hugo records this as a transient error, which later fails the load with a "failed to create config" wrapper.

Source

Thrown at config/allconfig/allconfig.go:317

		if newKind := kinds.IsDeprecatedAndReplacedWith(kind); newKind != "" {
			logger.Deprecatef(false, "Kind %q used in outputs configuration is deprecated, use %q instead.", kind, newKind)
			kind = newKind
		}
		if disabledKinds[kind] {
			continue
		}
		if kinds.GetKindAny(kind) == "" {
			logger.Warnf("Unknown kind %q in outputs configuration.", kind)
			continue
		}
		for _, format := range formats {
			if isRssDisabled && format == "rss" {
				// Legacy config.
				continue
			}
			f, found := outputFormats.GetByName(format)
			if !found {
				transientErr = fmt.Errorf("unknown output format %q for kind %q", format, kind)
				continue
			}
			kindOutputFormats[kind] = append(kindOutputFormats[kind], f)
		}
	}

	defaultOutputFormat := outputFormats[0]
	c.DefaultOutputFormat = strings.ToLower(c.DefaultOutputFormat)
	if c.DefaultOutputFormat != "" {
		f, found := outputFormats.GetByName(c.DefaultOutputFormat)
		if !found {
			return fmt.Errorf("unknown default output format %q", c.DefaultOutputFormat)
		}
		defaultOutputFormat = f
	} else {
		c.DefaultOutputFormat = defaultOutputFormat.Name
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Fix the spelling — format lookup matches defined names like HTML, RSS, JSON, AMP (case-insensitive).
2. Define the custom format under `[outputFormats.<Name>]` with `mediaType`, `baseName`, etc., before referencing it in `outputs`.
3. Run `hugo config` to see which output formats are actually defined after merging site + theme + module configs.

Example fix

# before
[outputs]
home = ["HTML", "SearchIndex"]
# after
[outputFormats.SearchIndex]
mediaType = "application/json"
baseName = "searchindex"
[outputs]
home = ["HTML", "SearchIndex"]

valid := map[string]bool{}
for _, f := range output.DefaultFormats {
    valid[strings.ToLower(f.Name)] = true
}
for kind, formats := range outputsConfig {
    for _, name := range formats {
        if !valid[strings.ToLower(name)] {
            return fmt.Errorf("outputs.%s references unknown format %q", kind, name)
        }
    }
}

When it happens

Trigger: An entry like `[outputs] home = ["HTML", "JSONN"]` naming a format not defined in `[outputFormats]`; defining a custom format in one config file but referencing it in another that loads without it (e.g. per-language or module config).

Common situations: Typos in format names, referencing a custom output format (e.g. "SearchIndex") before/without defining it under `[outputFormats]`, or a theme expecting a format the site config removed.

Related errors

• unknown default output format %q
• OutputFormat with key %q not found
• cannot determine BaseURL for protocol %q
• language %q not found
• unsupported format: %q

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