What causes "failed to decode output format configuration: %w" in gohugoio/hugo?

Read the wrapped cause after the colon — it names the exact field or media type that failed.

failed to decode output format configuration: %w

Error message

failed to decode output format configuration: %w

What it means

A wrapper error from output/config.go:139 emitted when mapstructure fails to decode the [outputFormats] configuration block into Hugo's output format struct. It wraps the underlying decode error (%w), which may itself be error 477/478 from the media-type hook or a generic type-mismatch from mapstructure. It means the overall shape of an output format entry doesn't fit the expected schema (name, mediaType, baseName, isPlainText, permalinkable, etc.).

Source

Thrown at output/config.go:139

							}
							dataVal.SetMapIndex(key, reflect.ValueOf(mediaType))
						default:
							return nil, fmt.Errorf("invalid output format configuration; wrong type for media type, expected string (e.g. text/html), got %T", vvi)
						}
					}
				}
			}
			return c, nil
		},
	}

	decoder, err := mapstructure.NewDecoder(config)
	if err != nil {
		return err
	}

	if err = decoder.Decode(input); err != nil {
		return fmt.Errorf("failed to decode output format configuration: %w", err)
	}

	return nil
}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Read the wrapped cause after the colon — it names the exact field or media type that failed.
Compare your [outputFormats] entry against the documented schema (mediaType string, baseName string, isPlainText/permalinkable bool, weight int) and fix the mismatched field.
Validate config syntax (hugo config) and fix YAML/TOML structure errors.
If the cause is a media type, apply the fixes for 'media type not found' (declare it under [mediaTypes]).

Example fix

# before
[outputFormats.SearchIndex]
isPlainText = "yes-please"

# after
[outputFormats.SearchIndex]
isPlainText = true
mediaType = "application/json"

Defensive patterns

Strategy: try-catch

Validate before calling

// Keep outputFormats entries to known keys with correct types:
// name (implicit), mediaType (string), baseName, path, rel (strings),
// isPlainText, isHTML, noUgly, notAlternative, permalinkable, weight (bool/int)

Try / catch

if err := loadConfig(); err != nil && strings.Contains(err.Error(), "failed to decode output format configuration") {
    // unwrap with errors.Unwrap / %+v to see the mapstructure field that failed, fix that key's type
}

Prevention

Match key names and value types exactly to the documented output format fields (booleans as booleans, weight as int)
Copy a documented outputFormats example as a starting point rather than hand-writing keys
Validate config changes in CI with a build before merging

When it happens

Trigger: Any decoder.Decode failure over outputFormats input: wrong-typed fields (e.g. isPlainText as a string that can't weakly coerce, weight as a non-number), unknown structural shapes, or hook errors like an unresolvable media type propagating up.

Common situations: Malformed [outputFormats] blocks after hand-editing TOML/YAML; indentation mistakes in YAML turning scalar fields into maps; copying config across Hugo versions with changed field names; the wrapped media-type errors above.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/a2fb42c28cc3d600.json. Report an issue: GitHub ↗.