What causes "failed to process %q: %w" in gohugoio/hugo?

Look at the wrapped inner error and the quoted target path — it names the exact output file and the real cause.

failed to process %q: %w

Error message

failed to process %q: %w

What it means

When Publish runs its transformer chain (minification, HTML element collection for build stats, live-reload injection, etc.) over the rendered content, any transformer failure is wrapped with the output's target path. It means the page rendered fine but a post-render output transformation failed for that specific file.

Source

Thrown at publisher/publisher.go:108

}

// Publish applies any relevant transformations and writes the file
// to its destination, e.g. /public.
func (p DestinationPublisher) Publish(d Descriptor) error {
	if d.TargetPath == "" {
		return errors.New("Publish: must provide a TargetPath")
	}

	src := d.Src

	transformers := p.createTransformerChain(d)

	if len(transformers) != 0 {
		b := bp.GetBuffer()
		defer bp.PutBuffer(b)

		if err := transformers.Apply(b, d.Src); err != nil {
			return fmt.Errorf("failed to process %q: %w", d.TargetPath, err)
		}

		// This is now what we write to disk.
		src = b
	}

	f, err := helpers.OpenFileForWriting(p.fs, d.TargetPath)
	if err != nil {
		return err
	}
	defer f.Close()

	var w io.Writer = f

	if p.htmlElementsCollector != nil && d.OutputFormat.IsHTML {
		w = io.MultiWriter(w, newHTMLElementsCollectorWriter(p.htmlElementsCollector))
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Look at the wrapped inner error and the quoted target path — it names the exact output file and the real cause.
Build without --minify (or minify=false) to confirm the file itself is valid, then fix the template producing the malformed output.
For JSON/XML outputs, validate the generated file (e.g. jq, xmllint) and fix escaping in the template (use jsonify instead of hand-built JSON).

Example fix

<!-- before: hand-built JSON breaks the minifier -->
{"title": "{{ .Title }}"}
<!-- after -->
{{ dict "title" .Title | jsonify }}

Defensive patterns

Strategy: try-catch

Try / catch

if err := pub.Publish(d); err != nil {
    // wrapped: "failed to process <path>: <cause>"
    return fmt.Errorf("publish %s: %w", d.TargetPath, errors.Unwrap(err))
}

Prevention

Inspect the wrapped cause with errors.Is/errors.As rather than string matching
The %q in the message names the failing output path — log it to locate the bad template/transform
Fail the build on this error; do not skip the file and continue

When it happens

Trigger: transformers.Apply returning an error inside DestinationPublisher.Publish — most commonly the minifier (`minify = true` / --minify) choking on malformed HTML/JS/CSS/JSON/XML output, or the HTML elements collector processing invalid markup when writeStats/buildStats is enabled.

Common situations: Enabling --minify on a site whose templates emit invalid JSON or malformed HTML; raw content passed through without escaping breaking the minifier; templates generating an XML/JSON output format with syntax errors that only surface at minify time.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/847cde92d88f449f.json. Report an issue: GitHub ↗.