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

Read the wrapped error text after 'failed to process shortcode:' — it identifies the real failure (missing partial, nil pointer, etc.).

gohugoio/hugo · error

failed to process shortcode

Error message

failed to process shortcode: %w

What it means

Hugo successfully located and invoked a shortcode template but executing it (template ExecuteWithContext at shortcode.go:776) returned an error. This is a thin wrapper; the underlying cause is appended via %w and is usually a Go template runtime error, a method call on a nil/typed value, or an error returned from a shortcode helper.

Solutions

Read the wrapped error text after 'failed to process shortcode:' — it identifies the real failure (missing partial, nil pointer, etc.).
Open the shortcode template (layouts/shortcodes/<name>.html) and locate the offending method/function call.
Add guards in the template ({{ with ... }}/{{ if ... }}) before chaining methods on optional values.
Verify referenced resources/partials exist under the current theme and Hugo version.

Example fix

// before (shortcode template)
<img src="{{ (.Resources.GetMatch (.Get "img")).RelPermalink }}">

// after
{{ with .Resources.GetMatch (.Get "img") }}
  <img src="{{ .RelPermalink }}">
{{ else }}
  {{ errorf "image %q not found" (.Get "img") }}
{{ end }}

Defensive patterns

Strategy: try-catch

Try / catch

// Shortcodes are invoked by Hugo's render pipeline; guard inside the template.
{{ with .Resources.GetMatch (.Get "img") }}
  <img src="{{ .RelPermalink }}">
{{ else }}
  {{ errorf "shortcode %q: image %q not found" .Name (.Get "img") }}
{{ end }}

Prevention

Guard optional values in shortcode templates with {{ with }} before chaining methods.
Use {{ errorf }} to emit a clear message instead of a nil-pointer template error.
Test shortcodes against minimal content in hugo server before broad use.

When it happens

Trigger: A shortcode template that calls a method that errors (e.g. .Page.Render on a missing layout, image processing on a missing resource, partial returning an error), references an undefined method, or hits a type mismatch during execution.

Common situations: Shortcode calls .Get on an index/key that does not exist and then chains a method; a resource transformation fails (missing image, unsupported format); a referenced partial is missing after a theme upgrade; a template uses a function removed in the current Hugo version.

Related errors

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

Appendix: source

Thrown at hugolib/shortcode.go:778

		}

		// This and other cool slice tricks: https://github.com/golang/go/wiki/SliceTricks
		source = append(source[:j], append(newVal, source[end:]...)...)
		start = j
		k = bytes.Index(source[start:], pre)

	}

	return source, nil
}

func renderShortcodeWithPage(ctx context.Context, h *tplimpl.TemplateStore, tmpl *tplimpl.TemplInfo, data *ShortcodeWithPage) (string, error) {
	buffer := bp.GetBuffer()
	defer bp.PutBuffer(buffer)

	err := h.ExecuteWithContext(ctx, tmpl, buffer, data)
	if err != nil {
		return "", fmt.Errorf("failed to process shortcode: %w", err)
	}
	return buffer.String(), nil
}

View on GitHub (pinned to 52c9bd7908)