gohugoio/hugo · error

%s: %w

Error message

%s: %w

What it means

This is an error-enrichment wrapper in addFileContext (templatestore.go:989). When a template execution fails, Hugo prepends a 'what' description (e.g. 'execute of template failed') to the underlying error via fmt.Errorf("%s: %w", what, inerr), then attempts to attach file/line context. The %s is the action description and %w preserves the original cause for unwrapping. It is the common envelope around template execution failures, not a distinct failure mode itself.

Source

Thrown at tpl/tplimpl/templatestore.go:989

					return 0
				}
			}
			return 0
		}

		f, err := fi.Meta().Open()
		if err != nil {
			return -1, inErr
		}
		defer f.Close()

		fe := herrors.NewFileErrorFromName(inErr, fi.Meta().Filename)
		fe.UpdateContent(f, lineMatcher)

		return matchWeight, fe
	}

	inerr = fmt.Errorf("%s: %w", what, inerr)

	var (
		err1    error
		weight1 int
		err2    error
		weight2 int
	)

	weight1, err1 = checkFilename(ti.Fi, inerr)

	if ti.base != nil {
		weight2, err2 = checkFilename(ti.base.Fi, inerr)
	}

	if err2 != nil && weight2 > weight1 {
		return err2
	}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Read the wrapped error (the %w portion) to find the true root cause; the %s prefix is only context.
2. Use the file/line info Hugo attaches to locate the offending template line.
3. Reproduce with `hugo --templateMetricsHints` or verbose logging for more detail.
4. Fix the underlying template error indicated by the wrapped cause.

Example fix

// before — template references undefined method
{{ .Page.NonExistentMethod }}

// after — use a valid field/method with a guard
{{ with .Page.Title }}{{ . }}{{ end }}

// When calling Hugo programmatically (hugolib.Test or library use),
// wrap the build and unwrap to reach the root cause:
if err := b.Build(BuildCfg{}); err != nil {
    // errors.Is/As to unwrap the %w chain to the original parse/exec error
    var fe *herrors.FileError
    if errors.As(err, &fe) {
        log.Printf("template error at %s:%d: %v", fe.File().Filename(), fe.LineNumber(), fe)
    }
}

When it happens

Trigger: Any template execution error (bad function call, type mismatch, nil dereference in a template pipe, missing partial during execution) flowing through ExecuteWithContext -> addFileContext at templatestore.go:550.

Common situations: Calling a non-existent template function; passing the wrong type to a Hugo function inside a template; referencing .Params on a nil page; any runtime template error during `hugo`/`hugo server`.

Related errors

• failed to build JS batch: %w
• template: %s:%d: %s
• maximum template call stack size exceeded in %q
• failed to transform template %q: %w
• inner cannot be used inside a with block that wraps a partia

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