gohugoio/hugo · error

OutputFormat with key %q not found

Error message

OutputFormat with key %q not found

What it means

Raised by `Formats.GetByNames` in output/outputFormat.go when one of the requested output-format identifiers (e.g. "HTML", "RSS", "JSON") has no matching entry in Hugo's resolved output formats collection. Hugo looks each name up case-insensitively via `GetByName`; the first miss aborts with this error. It typically surfaces while decoding the site's `outputs` configuration or a page's `outputs` front matter into concrete formats.

Source

Thrown at output/outputFormat.go:305

func (formats Formats) GetByName(name string) (f Format, found bool) {
	for _, ff := range formats {
		if strings.EqualFold(name, ff.Name) {
			f = ff
			found = true
			return
		}
	}
	return
}

// GetByNames gets a list of formats given a list of identifiers.
func (formats Formats) GetByNames(names ...string) (Formats, error) {
	var types []Format

	for _, name := range names {
		tpe, ok := formats.GetByName(name)
		if !ok {
			return types, fmt.Errorf("OutputFormat with key %q not found", name)
		}
		types = append(types, tpe)
	}
	return types, nil
}

// BaseFilename returns the base filename of f including an extension (ie.
// "index.xml").
func (f Format) BaseFilename() string {
	return f.BaseName + f.MediaType.FirstSuffix.FullSuffix
}

// IsZero returns true if f represents a zero value.
func (f Format) IsZero() bool {
	return f.Name == ""
}

// MarshalJSON returns the JSON encoding of f.

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Check the spelling of every name under `outputs` in site config and page front matter against built-in formats (html, rss, json, amp, calendar, etc.).
2. If it's a custom format, define it under `[outputFormats.<name>]` (with a `mediaType`) in the same merged configuration.
3. Run `hugo config | grep -i outputformats` to see which formats are actually registered after config merging.
4. If the name comes from a theme, ensure the theme's config is loaded (check `theme`/module imports).

Example fix

# before (hugo.toml)
[outputs]
home = ["HTML", "SearchIndx"]

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

if _, found := outputFormats.GetByName(key); !found {
    return fmt.Errorf("unknown output format %q", key)
}

if err != nil && strings.Contains(err.Error(), "not found") {
    // list valid formats for the user
}

When it happens

Trigger: Setting `outputs` in site config (e.g. `[outputs] home = ['HTML','SearchIndex']`) or `outputs:` in page front matter with a name that is not built in and not defined under `[outputFormats]`; also `outputFormats.Get` lookups in templates or cascade-applied outputs referencing a removed custom format.

Common situations: Typos in format names in config; defining a custom output format in one config file but referencing it in an environment config where the definition isn't merged; copying a theme's `outputs` config without its `[outputFormats]` block; a theme update renaming a custom format.

Related errors

• unknown output format %q for kind %q
• unknown default output format %q
• 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/ce9ab86be5465cf8.json. Report an issue: GitHub ↗.