gohugoio/hugo · error

failed to render shortcode

Error message

failed to render shortcode %q: %w

What it means

Generic wrapper emitted by prepareShortcode's toParseErr (shortcode.go:332). Any failure inside doRenderShortcode (template lookup, parse, execution) or the subsequent renderShortcode is wrapped with the shortcode name and surfaced with source position via parseError. The underlying cause is in the wrapped error chain.

Solutions

1. Read the wrapped error — it names the shortcode and the inner cause; open that template and fix the reported issue.
2. Reproduce with a minimal content snippet and run `hugo server` for live error context.
3. Add `with`/`default` guards in the shortcode template for params that may be absent or mistyped.

Example fix

{{/* before (layouts/shortcodes/note.html) */}}
{{ .Get "type" | upper }}

{{/* after: guard against missing param */}}
{{ with .Get "type" }}{{ . | upper }}{{ end }}

{{/* Guard shortcode params to prevent runtime errors in the template */}}
{{ $type := .Get "type" | default "info" }}
{{ with .Get "title" }}{{ . }}{{ end }}

When it happens

Trigger: A shortcode template references an undefined function or method; passes wrong argument types; raises a runtime error (nil deref in template, division by zero); a nested shortcode errors; the shortcode template file has a Go-template syntax error.

Common situations: Editing a shortcode template and introducing a bug; content that exercises a previously-unreached code path in the shortcode; theme upgrade where a shortcode helper changed signature; passing unexpected param types from content.

Related errors

• failed to execute template
• failed to render shortcode
• no earlier definition of shortcode
• : shortcode does not evaluate .Inner or .InnerDeindent, yet…
• : template for shortcode not found

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

Appendix: source

Thrown at hugolib/shortcode.go:332

}

const (
	innerNewlineRegexp = "\n"
	innerCleanupRegexp = `\A<p>(.*)</p>\n\z`
	innerCleanupExpand = "$1"
)

func prepareShortcode(
	level int,
	sc *shortcode,
	parent *ShortcodeWithPage,
	po *pageOutput,
	isRenderString bool,
) (shortcodeRenderer, error) {
	p := po.p
	toParseErr := func(err error) error {
		source := p.m.content.mustSource()
		return p.parseError(fmt.Errorf("failed to render shortcode %q: %w", sc.name, err), source, sc.pos)
	}

	// Allow the caller to delay the rendering of the shortcode if needed.
	var fn shortcodeRenderFunc = func(ctx context.Context) ([]byte, bool, error) {
		if p.m.pageConfigSource.ContentMediaType.IsMarkdown() && sc.doMarkup {
			// Signal downwards that the content rendered will be
			// parsed and rendered by Goldmark.
			ctx = tpl.Context.IsInGoldmark.Set(ctx, true)
		}
		r, err := doRenderShortcode(ctx, level, po.p.s.TemplateStore, sc, parent, po, isRenderString)
		if err != nil {
			return nil, false, toParseErr(err)
		}

		b, hasVariants, err := r.renderShortcode(ctx)
		if err != nil {
			return nil, false, toParseErr(err)
		}

View on GitHub (pinned to 52c9bd7908)