What causes "Publish: must provide a TargetPath" in gohugoio/hugo?

If embedding Hugo as a library, set Descriptor.TargetPath before calling Publish.

Publish: must provide a TargetPath

Error message

Publish: must provide a TargetPath

What it means

DestinationPublisher.Publish writes a rendered output file to the destination filesystem (e.g. /public). The Descriptor it receives must carry a non-empty TargetPath — the relative path to write to. An empty TargetPath means there is nowhere to write, so Hugo fails fast instead of silently dropping output.

Source

Thrown at publisher/publisher.go:96

// NewDestinationPublisher creates a new DestinationPublisher.
func NewDestinationPublisher(rs *resources.Spec, outputFormats output.Formats, mediaTypes media.Types) (pub DestinationPublisher, err error) {
	fs := rs.BaseFs.PublishFs
	cfg := rs.Cfg
	var classCollector *htmlElementsCollector
	if rs.BuildConfig().BuildStats.Enabled() {
		classCollector = newHTMLElementsCollector(rs.BuildConfig().BuildStats)
	}
	pub = DestinationPublisher{fs: fs, htmlElementsCollector: classCollector}
	pub.min, err = minifiers.New(mediaTypes, outputFormats, cfg)
	return
}

// 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
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

If embedding Hugo as a library, set Descriptor.TargetPath before calling Publish.
If seen from a normal Hugo build, check permalink and outputs config for entries that could resolve to an empty path.
Report it as a Hugo bug with a minimal reproducer if config looks sane — this is an internal invariant violation.

Example fix

// before
p.Publish(publisher.Descriptor{Src: r})
// after
p.Publish(publisher.Descriptor{Src: r, TargetPath: "index.html", OutputFormat: f})

Defensive patterns

Strategy: validation

Validate before calling

if d.TargetPath == "" {
    return errors.New("descriptor missing TargetPath")
}

Prevention

Always populate Descriptor.TargetPath before calling Publish
Use a constructor/helper that requires the target path instead of a bare struct literal
Assert non-empty output paths in unit tests for any code building publish descriptors

When it happens

Trigger: Calling Publish with a Descriptor whose TargetPath field is the empty string. In practice this is an internal invariant: it surfaces when render hooks/output-format plumbing (or code embedding Hugo as a library) constructs a Descriptor without setting the target path.

Common situations: Programs embedding Hugo's publisher package directly and forgetting to set Descriptor.TargetPath; in rare cases a Hugo bug where an output format resolves to an empty permalink/path, e.g. malformed permalink config producing an empty path.

Related errors

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