gohugoio/hugo · warning

unknown output format

Error message

unknown output format %q for kind %q

What it means

Recorded as a transient error during CompileConfig when an entry in the `outputs` map references an output format name that is not present in the configured outputFormats set (outputFormats.GetByName returns false). The message names both the missing format and the kind it was declared for.

Solutions

1. Check the exact format name against `outputFormats` keys and built-in names.
2. Add the missing format definition under `outputFormats` if intended.
3. Remove the stale entry from the `outputs` map.
4. Mind case: built-in names are uppercase (HTML, RSS, JSON, AMP, CSV, etc.).

Example fix

// before
[outputs]
home = ["HTML", "HTMl"]
// after
[outputs]
home = ["HTML"]

func knownFormats(cfg output.Formats, names []string) error {
  for _, n := range names { if _, ok := cfg.GetByName(n); !ok { return fmt.Errorf("unknown format %q", n) } }
  return nil
}

When it happens

Trigger: Declaring `outputs: { home: ["HTML","JSON","FOO"] }` when 'FOO' is neither a built-in format nor defined under `outputFormats`. Typos in format names or referencing a custom format that was never defined both trigger it.

Common situations: Renaming/removing a custom output format without updating the `outputs` map; typos like 'Html' vs 'HTML' (lookups are case-sensitive on the name); theme overrides that drop a format the content assumes.

Related errors

• unknown default output format
• failed to compile ignoreFiles pattern
• failed to parse clock
• failed to parse timeout
• invalid language configuration for

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

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