gohugoio/hugo · error

failed to process

Error message

failed to process %q: %w

What it means

Returned by DestinationPublisher.Publish when the transformer chain (URL rewriting, livereload injection, generator tag injection, or minification) fails to apply to the source content. It wraps the transformer error and names the TargetPath so the failing output file is identifiable. This is the final transformation step before the file is written to the publish filesystem.

Solutions

1. Disable minify for the affected output format and re-run to isolate whether the minifier is the cause.
2. Inspect the wrapped error to identify which transformer (absURL, livereload, generator, minify) failed.
3. Fix the template producing malformed HTML/XML so the transformer can parse it.
4. Verify the output format and media type have a registered minifier if minify is enabled.

Example fix

// before: minify enabled, malformed HTML in template breaks publish
minify: true

// after: fix the template output, or scope minify
[minify]
minifyOutput = true
disableXML = true  # if XML minifier is the culprit

// Validate content is well-formed before publishing; disable minify to isolate.
func safePublish(p publisher.Publisher, d publisher.Descriptor, minify bool) error {
    d.Minify = minify
    if minify {
        peek, err := io.ReadAll(d.Src)
        if err != nil { return err }
        d.Src = bytes.NewReader(peek)
        // optionally validate HTML parseability here
    }
    return p.Publish(d)
}

if err := p.Publish(d); err != nil {
    // err already names the TargetPath; inspect wrapped cause
    return err
}

When it happens

Trigger: Publishing a Descriptor whose Src contains malformed HTML/XML that breaks the minifier or URL replacer, enabling minify with an output format lacking a registered minifier config, or injecting livereload/generator transforms on content the transformer cannot parse.

Common situations: Enabling minify = true in config for an output format with no matching minifier, a template producing invalid HTML that the minifier rejects, or a URL replacement transform failing on non-absolute-able URLs.

Related errors

• cannot transform content of Resource of type %T
• failed to add internal partial decorator template
• failed to copy to
• failed to create internal partial decorator template
• failed to create page from pageMetaSource

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

Appendix: 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 52c9bd7908)