gohugoio/hugo · error

OutputFormat with key

Error message

OutputFormat with key %q not found

What it means

Thrown by Formats.GetByNames (output/outputFormat.go:305) when one of the requested output format names is not present in the slice of configured Formats. Hugo iterates the names and, for any name with no case-insensitive match in the Formats slice, returns this error naming the missing key. This is the error behind an unknown output format referenced in a page's 'outputs' front matter or the site [outputs] config.

Solutions

1. Check the exact name in the error and ensure an [outputFormats.NAME] with that Name exists (or use a built-in like HTML, AMP, RSS, JSON, CSV).
2. If it is a custom format, add the full [outputFormats.NAME] definition.
3. Update the [outputs] config or page front matter to remove the unknown format if it is no longer wanted.
4. Run hugo config to print the list of resolved output formats and confirm the name matches.

Example fix

# before (json output requested but not defined)
[outputs]
home = ["html", "json"]

# after (define the format or remove the reference)
[outputFormats.json]
mediaType = "application/json"
baseName = "index"
[outputs]
home = ["html", "json"]

// Verify each requested output name exists before GetByNames.
func allFormatsExist(formats output.Formats, names []string) error {
    for _, n := range names {
        if _, ok := formats.GetByName(n); !ok {
            return fmt.Errorf("output format %q not defined", n)
        }
    }
    return nil
}

got, err := formats.GetByNames(want...)
if err != nil {
    return fmt.Errorf("referenced output format missing: %w", err)
}

When it happens

Trigger: A page or section lists outputs = ["html", "AMP"] but AMP is not enabled; site config [outputs] home = ["html", "json"] where the JSON format was never defined or was removed by a theme change; referencing a custom format name that has a typo or differing case that doesn't match the registered Name.

Common situations: Enabling outputs for a format you forgot to define in [outputFormats]; renaming an output format without updating references; a theme swap that removes a previously available format; case mismatch (e.g. 'amp' vs 'AMP' — note EqualFold is used so case is fine, but the format must exist).

Related errors

• failed convert config to map
• failed to decode output format configuration
• invalid output format configuration; wrong type for media…
• media type not found
• --appendPort=false not supported when in multihost mode

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

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