gohugoio/hugo · error

failed to create internal partial decorator template %q: %w

Error message

failed to create internal partial decorator template %q: %w

What it means

While creating an internal partial decorator for a {{ with partial ... }} block, Hugo calls store.addTransformedTemplateInsert to register the synthesized template under _partials/_internal/decorator_<hash> (templatetransform.go:340-343). If that insertion returns an error, it is wrapped with the internal template name. This is an internal failure during the decorator-synthesis step.

Source

Thrown at tpl/tplimpl/templatetransform.go:342

func (c *templateTransformContext) handleWithPartial(withNode *parse.WithNode) {
	withNodeInnerString := withNode.List.String()
	if templatesInnerRe.MatchString(withNodeInnerString) {
		c.err = fmt.Errorf("inner cannot be used inside a with block that wraps a partial decorator")
		return
	}

	// See #14333. That is a very odd construct, but we need to guard against it.
	if c.hasBreakOrContinueOutsideRange(withNode.List) {
		return
	}
	innerHash := hashing.XxHashFromStringHexEncoded(c.t.Name() + withNodeInnerString)
	internalPartialName := fmt.Sprintf("_partials/%s%s", PartialDecoratorPrefix, innerHash)

	if c.lookupFn(internalPartialName, c.t) == nil {
		innerCopy := withNode.List.CopyList()
		ti, err := c.store.addTransformedTemplateInsert(internalPartialName, SubCategoryInline)
		if err != nil {
			c.err = fmt.Errorf("failed to create internal partial decorator template %q: %w", internalPartialName, err)
			return
		}
		if ti == nil {
			c.err = fmt.Errorf("failed to find internal partial decorator template %q after insertion", internalPartialName)
			return
		}

		cc := newTemplateTransformContext(ti, c.store, c.lookupFn)

		tree, err := c.store.addTransformedTemplateSetTree(ti, innerCopy)
		if err != nil {
			c.err = fmt.Errorf("failed to add internal partial decorator template %q: %w", internalPartialName, err)
			return
		}

		if err := cc.applyTransformationsAndSetReturnWrapper(tree); err != nil {
			c.err = fmt.Errorf("failed to transform internal partial decorator template %q: %w", internalPartialName, err)
			return

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Read the wrapped error for the root cause from addTransformedTemplateInsert.
2. Simplify the with-partial block to see if the error disappears, then re-add constructs incrementally.
3. Report as a Hugo bug with the template and Hugo version if it reproduces on clean Hugo.
4. Update to the latest Hugo release.

// Internal error — surface the wrapped cause in tests:
if err != nil && strings.Contains(err.Error(), "failed to create internal partial decorator") {
    t.Fatalf("internal decorator creation failed: %v", err)
}

When it happens

Trigger: A failure inside addTransformedTemplateInsert when registering the synthesized decorator template — typically a deeper internal error in the template store (e.g. key collision, descriptor extraction failure). Triggered during the transform pass for a with-partial construct.

Common situations: Rare; usually indicates a Hugo internal bug or an extremely unusual template structure that exercises an unhandled path in template insertion. May appear during Hugo development or with edge-case template patterns.

Related errors

• failed to add internal partial decorator template %q: %w
• failed to transform internal partial decorator template %q:
• inner cannot be used inside a with block that wraps a partia
• failed to find internal partial decorator template %q after
• maximum template call stack size exceeded in %q

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