gohugoio/hugo · critical

transformerRaw is required

Error message

transformerRaw is required

What it means

A panic in NodeShiftTree.AppendRaw (hugolib/doctree/nodeshifttree.go:310) when transformerRaw is nil. AppendRaw needs a Transformer to combine values, so a tree constructed without TransformerRaw cannot service AppendRaw calls.

Source

Thrown at hugolib/doctree/nodeshifttree.go:310

func (r *NodeShiftTree[T]) LongestPrefixRaw(s string) (string, bool) {
	s, _, found := r.tree.LongestPrefix(s)
	return s, found
}

// GetRaw returns the raw value at the given key without any shifting or transformation.
func (r *NodeShiftTree[T]) GetRaw(s string) (T, bool) {
	v, ok := r.tree.Get(s)
	if !ok {
		var t T
		return t, false
	}
	return v, true
}

// AppendRaw appends ts to the node at the given key without any shifting or transformation.
func (r *NodeShiftTree[T]) AppendRaw(s string, ts ...T) (T, bool) {
	if r.transformerRaw == nil {
		panic("transformerRaw is required")
	}
	n, found := r.GetRaw(s)
	n2, replaced := r.transformerRaw.Append(n, ts...)
	if replaced || !found {
		r.insert(s, n2)
	}
	return n2, replaced || !found
}

// WalkPrefixRaw walks all nodes with the given prefix in the tree without any shifting or transformation.
func (r *NodeShiftTree[T]) WalkPrefixRaw(prefix string, fn radix.WalkFn[T]) error {
	return r.tree.WalkPrefix(prefix, fn)
}

// Shape returns a new NodeShiftTree shaped to the given dimension.
func (t *NodeShiftTree[T]) Shape(v sitesmatrix.Vector) *NodeShiftTree[T] {
	x := t.clone()
	x.siteVector = v

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Provide a TransformerRaw in Config if you need AppendRaw
2. Use Insert/InsertRaw instead, which do not require transformerRaw

Example fix

// before
tree := doctree.New(t)
// after
tree := doctree.New(doctree.Config{Shifter: s, TransformerRaw: tr})

if tree.transformerRaw == nil {
    return errors.New("AppendRaw requires a TransformerRaw")
}

When it happens

Trigger: Constructing a NodeShiftTree with Config.TransformerRaw nil and then calling AppendRaw.

Common situations: Embedded Hugo use that builds a tree for read-only/shift operations but then calls AppendRaw on it.

Related errors

• Shifter is required
• Transform must be performed with NoShift=true
• Handle cannot replace nodes in the tree, use Transform for t
• DeleteFunc: unknown type %T
• Insert: unknown type %T

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