gohugoio/hugo · error

failed to decode page map: %w

Error message

failed to decode page map: %w

What it means

Thrown by PageConfigLate.Compile when a page is flagged as coming from a content adapter (IsFromContentAdapter) and mapstructure.WeakDecode of ContentAdapterData into the PageConfigLate struct fails. The wrapped error is the decode failure, meaning the data map produced by the adapter does not fit the page-config schema.

Source

Thrown at resources/page/pagemeta/page_frontmatter.go:443

			p.ContentMediaType = MarkupToMediaType(s, mediaTypes)
		}
	}

	if p.ContentMediaType.IsZero() {
		return fmt.Errorf("failed to resolve media type for %q", s)
	}

	if p.Content.Markup == "" {
		p.Content.Markup = p.ContentMediaType.SubType
	}
	return nil
}

// Compile sets up the page configuration after all fields have been set.
func (p *PageConfigLate) Compile(e *PageConfigEarly, logger loggers.Logger, outputFormats output.Formats) error {
	if e.IsFromContentAdapter {
		if err := mapstructure.WeakDecode(p.ContentAdapterData, p); err != nil {
			err = fmt.Errorf("failed to decode page map: %w", err)
			return err
		}
	}

	if p.Params == nil {
		p.Params = make(hmaps.Params)
	} else {
		hmaps.PrepareParams(p.Params)
	}

	if len(p.Outputs) > 0 {
		outFormats, err := outputFormats.GetByNames(p.Outputs...)
		if err != nil {
			return fmt.Errorf("failed to resolve output formats %v: %w", p.Outputs, err)
		} else {
			p.ConfiguredOutputFormats = outFormats
		}
	}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Inspect the wrapped error for the offending field name and type mismatch.
2. Coerce the adapter's data values to the types expected by PageConfigLate (int for Weight, []string for Outputs, bool for Draft, etc.).
3. Keep unknown/extra keys under Params rather than at the top level of the data map.

Example fix

// before
data := map[string]any{"weight": "5", "outputs": "html"}
// after
data := map[string]any{"weight": 5, "outputs": []string{"html"}}

if err := mapstructure.WeakDecode(data, &pagemeta.PageConfigLate{}); err != nil {
    return fmt.Errorf("adapter data shape invalid: %w", err)
}

if err := pcfg.Compile(early, logger, formats); err != nil {
    logger.Errorf("content adapter data for %s: %v", path, err)
    return err
}

When it happens

Trigger: A content adapter populates ContentAdapterData with keys whose types are incompatible with PageConfigLate fields, e.g. 'weight: "five"' (string into int) or 'outputs: 42' (int into []string).

Common situations: Custom content adapters feeding unvalidated data from an external API/JSON into page config; schema drift between the adapter's source data and Hugo's PageConfigLate fields after an upgrade.

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

• markup must not be set, use mediaType
• failed to decode sites from front matter: %w
• failed to resolve media type for %q
• failed to resolve output formats %v: %w
• media type %q not found

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