gohugoio/hugo · error

failed to parse empty HTML template %q: %w

Error message

failed to parse empty HTML template %q: %w

What it means

The HTML counterpart of the empty text template parse: in addDeferredTemplate (templatestore.go:931-935) the HTML template prototype's New(name).Parse("") is used to seed a deferred HTML template. Failure here wraps the underlying html/template parse error. Parsing an empty string should not fail, so this indicates an anomalous/internal condition.

Source

Thrown at tpl/tplimpl/templatestore.go:935

	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,
	})

	return nil
}

func (s *TemplateStore) addFileContext(ti *TemplInfo, what string, inerr error) error {
	if ti.Fi == nil {
		return inerr

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Treat as a Hugo internal error; report with the template name and Hugo version.
2. Upgrade Hugo to the latest stable release.
3. Bisect recently added templates/layouts to find a trigger if reproducible.
4. Avoid any code that mutates the internal parseHTML prototype.

// Internal error; in Go integration tests, surface distinctly:
if strings.Contains(err.Error(), "failed to parse empty HTML template") {
    t.Fatalf("Hugo internal HTML template parse failure: %v", err)
}

When it happens

Trigger: Internal registration of a deferred HTML template where the htmltemplate prototype is corrupted or its func map is in an invalid state. Surfaces during build when deferred rendering constructs are processed.

Common situations: Not expected in normal builds. Could appear in Hugo development/forking scenarios where the html template prototype's funcs are modified, or due to a regression in a Hugo release affecting the deferred template path.

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 text 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/12432e1eabab658e. Report an issue: GitHub.