gohugoio/hugo · error

unknown default output format %q

Error message

unknown default output format %q

What it means

The top-level `defaultOutputFormat` setting names which output format is the primary one (used for canonical permalinks etc.). Hugo lowercases the value and looks it up in the compiled output formats; if not found, config compilation aborts. Unlike per-kind unknown formats (a transient error), this one returns immediately.

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 8a468df065)

Solutions

1. Correct the value to an existing format name, e.g. `defaultOutputFormat = "html"`.
2. If it should be a custom format, define it under `[outputFormats]` first.
3. Remove the setting entirely to let Hugo default to the first configured output format.

Example fix

# before
defaultOutputFormat = "htlm"
# after
defaultOutputFormat = "html"

if name := cfg.DefaultOutputFormat; name != "" {
    if _, found := allFormats.GetByName(name); !found {
        return fmt.Errorf("defaultOutputFormat %q is not a defined output format", name)
    }
}

When it happens

Trigger: Setting `defaultOutputFormat = "htmll"` or naming a custom format that isn't defined under `[outputFormats]` when `Config.CompileConfig` runs.

Common situations: Typos, removing a custom output format definition while leaving `defaultOutputFormat` pointing at it, or setting it in a language-specific config where the format isn't visible.

Related errors

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