gohugoio/hugo · error

failed to decode $_hugo_config in template: %w

Error message

failed to decode $_hugo_config in template: %w

What it means

Hugo templates may declare a config via {{ $_hugo_config := `{...}` }}. The transformer (templatetransform.go:507-512) first converts the string node's text to a map via hmaps.ToStringMapE. If the JSON-ish string cannot be turned into a string-keyed map, this error wraps the conversion failure. This is the first of two decode failure points for $_hugo_config.

Source

Thrown at tpl/tplimpl/templatetransform.go:511

	}

	v := n.Decl[0]

	if len(v.Ident) == 0 || v.Ident[0] != "$_hugo_config" {
		return
	}

	cmd := n.Cmds[0]

	if len(cmd.Args) == 0 {
		return
	}

	if s, ok := cmd.Args[0].(*parse.StringNode); ok {
		errMsg := "failed to decode $_hugo_config in template: %w"
		m, err := hmaps.ToStringMapE(s.Text)
		if err != nil {
			c.err = fmt.Errorf(errMsg, err)
			return
		}
		if err := mapstructure.WeakDecode(m, &c.t.ParseInfo.Config); err != nil {
			c.err = fmt.Errorf(errMsg, err)
		}
	}
}

// collectInnerInShortcode determines if the given CommandNode represents a
// shortcode call to its .Inner.
func (c *templateTransformContext) collectInnerInShortcode(n *parse.CommandNode) {
	if c.t.category != CategoryShortcode {
		return
	}
	if c.t.ParseInfo.IsInner || len(n.Args) == 0 {
		return
	}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Validate the $_hugo_config JSON with a linter; ensure it is a JSON object.
2. Check for unescaped quotes or trailing commas in the config string.
3. Use the documented schema (e.g. {"version": 1}).

Example fix

// before
{{ $_hugo_config := `{version: 1,}` }}

// after — valid JSON object
{{ $_hugo_config := `{"version": 1}` }}

// Validate the $_hugo_config JSON before relying on it. It must be a JSON object:
{{ $_hugo_config := `{"version": 1}` }}
// Avoid arrays, scalars, or malformed JSON.

When it happens

Trigger: A template declares {{ $_hugo_config := "..." }} but the string is not valid JSON or does not decode into a map[string]any (e.g. a bare string, a JSON array, malformed JSON). ToStringMapE rejects non-map results.

Common situations: Hand-writing a $_hugo_config with a syntax error; missing quotes; providing a scalar instead of a JSON object; copy-paste errors from documentation.

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

• failed to transform template %q: %w
• must provide cache Dir
• no sites to build
• targetPath cannot be empty
• config needs a filename

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