gohugoio/hugo · error

failed to parse empty text template %q: %w

Error message

failed to parse empty text template %q: %w

What it means

When Hugo registers a deferred text template (via addDeferredTemplate, templatestore.go:916-927), it parses an empty string with the text template prototype as a seed and then swaps in the deferred node list. If that empty-string parse fails (prototype.New(name).Parse("")), the error wraps the underlying parse error. An empty parse failing is an exceptional/internal condition since the input is the literal empty string.

Source

Thrown at tpl/tplimpl/templatestore.go:927

		if best.isBetter(weight, vv) {
			best.updateValues(weight, k2, k.d, vv)
		}
	}
}

func (t *TemplateStore) addDeferredTemplate(owner *TemplInfo, name string, n *parse.ListNode) error {
	if _, found := t.templatesByPath.Get(name); found {
		return nil
	}

	var templ tpl.Template

	if owner.D.IsPlainText {
		prototype := t.tns.parseText
		tt, err := prototype.New(name).Parse("")
		if err != nil {
			return fmt.Errorf("failed to parse empty text template %q: %w", name, err)
		}
		tt.Tree.Root = n
		templ = tt
	} else {
		prototype := t.tns.parseHTML
		tt, err := prototype.New(name).Parse("")
		if err != nil {
			return fmt.Errorf("failed to parse empty HTML template %q: %w", name, err)
		}
		tt.Tree.Root = n
		templ = tt
	}

	t.templatesByPath.Set(name, &TemplInfo{
		Fi:       owner.Fi,
		PathInfo: owner.PathInfo,
		D:        owner.D,
		Template: templ,

View on GitHub (pinned to 52c9bd7908)

Solutions

1. If seen in a standard Hugo build, report it as a Hugo bug with the template name from the error.
2. Check for any custom code that mutates the parseText prototype template.
3. Update to the latest Hugo patch release to pick up fixes to the deferred-template machinery.
4. Isolate which content/template triggers it by bisecting recently added layouts.

// This is an internal Hugo error. In Hugo's Go tests, treat any build error
// matching this message as a fatal/internal failure:
if strings.Contains(err.Error(), "failed to parse empty text template") {
    t.Fatalf("internal Hugo template error: %v", err)
}

When it happens

Trigger: Triggered internally when processing templates that use Hugo's deferred rendering (e.g. {{ doDefer ... }} or pagination/defer blocks) and the text template prototype is in a corrupt or unexpectedly-modified state. This is not a user-content-driven error under normal Hugo internals.

Common situations: Almost never seen in normal use because parsing an empty string should always succeed. Could surface if a custom fork modifies the prototype template or injects broken funcs, or in edge cases with conflicting template namespaces during development of Hugo itself.

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 parse empty HTML template %q: %w
• failed to parse Resource %q as Template:: %w
• failed to transform template %q: %w
• failed to create internal partial decorator template %q: %w
• failed to find internal partial decorator template %q after

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