gohugoio/hugo · error

unknown default output format

Error message

unknown default output format %q

What it means

Returned (fatally, not transient) by CompileConfig when `defaultOutputFormat` names a format not found via outputFormats.GetByName. Unlike error 253, this is the single site-wide default and aborts config compilation entirely.

Solutions

1. Set defaultOutputFormat to a registered format name (built-in or custom under outputFormats).
2. Leave it empty/unset to use the default (HTML).
3. Verify the exact case-sensitive name against outputFormats keys.

Example fix

// before
defaultOutputFormat = "html"
// after
defaultOutputFormat = "HTML"

func validateDefaultFormat(cfg output.Formats, name string) error {
  if name == "" { return nil }
  if _, ok := cfg.GetByName(name); !ok { return fmt.Errorf("unknown default output format %q", name) }
  return nil
}

When it happens

Trigger: Setting `defaultOutputFormat = "FOO"` in config when 'FOO' is not a registered output format. Empty value is allowed (defaults to the first format, normally HTML); an unknown non-empty value is not.

Common situations: Typos in defaultOutputFormat (e.g. 'html' lowercase vs 'HTML'), referencing a custom format that was removed, or copy-pasting a theme config whose custom format is not installed.

Related errors

• unknown 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/cdfe7a564668c78b. Report an issue: GitHub.

Appendix: source

Thrown at config/allconfig/allconfig.go:329

			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
	}

	disabledLangs := make(map[string]bool)
	for _, lang := range c.DisableLanguages {
		disabledLangs[lang] = true
	}

	for i, s := range c.IgnoreLogs {
		c.IgnoreLogs[i] = strings.ToLower(s)
	}

	ignoredLogIDs := make(map[string]bool)
	for _, err := range c.IgnoreLogs {
		ignoredLogIDs[err] = true

View on GitHub (pinned to 52c9bd7908)