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

Read the wrapped mapstructure error to find the offending field name and expected type.

failed to decode output format configuration

Error message

failed to decode output format configuration: %w

What it means

Thrown by output.decode (output/config.go:139) when mapstructure's decoder.Decode(input) returns an error while decoding a single output format's config map into a Format struct. The %w wraps the mapstructure error, which usually indicates an unrecognized field, a type that WeaklyTypedInput cannot coerce, or a struct field constraint violation (e.g. isHTML expects bool).

Solutions

Read the wrapped mapstructure error to find the offending field name and expected type.
Correct the field value type in [outputFormats.NAME] to match the Format struct (BaseName string, Rel string, IsHTML bool, etc.).
Remove any unrecognized/renamed fields.
Run hugo config to verify the resolved outputFormats section parses cleanly.

Example fix

# before
[outputFormats.MYFORMAT]
mediaType = "text/html"
weight = "heavy"   # expects int

# after
[outputFormats.MYFORMAT]
mediaType = "text/html"
weight = 10

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate known Format fields against expected types.
var formatFieldTypes = map[string]string{
    "baseName": "string", "rel": "string", "weight": "int", "isHTML": "bool",
}

Try / catch

if err := output.DecodeConfig(mediaTypes, in); err != nil {
    return fmt.Errorf("fix outputFormats field types: %w", err)
}

Prevention

Match each outputFormat field to the documented type.
Remove deprecated/renamed fields after Hugo upgrades.
Use `hugo config` to confirm clean parsing.

When it happens

Trigger: A custom output format defines a field with an incompatible type (e.g. weight = "abc" where an int is expected, or isPlainText = "yes" which weak-typing may or may not coerce); an unknown field name that mapstructure rejects under its error policy; a nested structure where a scalar is expected.

Common situations: Typos in output format field names; copy-pasting a config snippet from a different Hugo version with renamed fields; using a string where a bool/int is required and weak typing cannot reconcile it.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

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