gohugoio/hugo · error

failed to render shortcode %q: %w

Error message

failed to render shortcode %q: %w

What it means

This wraps any failure that occurs while rendering a specific shortcode on a page — template resolution, template execution, or rendering of its output. Hugo attaches the shortcode name and, via p.parseError with the shortcode's source position, the file and line so the user can locate the failing shortcode call in their content.

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 8a468df065)

Solutions

1. Read the wrapped error — it identifies the actual template failure; fix that expression in layouts/_shortcodes/<name>.html.
2. Guard optional params in the shortcode template (e.g. {{ with .Get "param" }}...{{ end }}).
3. Reproduce with 'hugo --panicOnWarning=false -v' or 'hugo server' to get the file:line position reported and inspect that shortcode invocation in the content file.

Example fix

{{/* before: layouts/_shortcodes/img.html */}}
<img src="{{ (resources.Get (.Get "src")).RelPermalink }}">

{{/* after */}}
{{ with resources.Get (.Get "src") }}
<img src="{{ .RelPermalink }}">
{{ else }}
{{ errorf "img shortcode: resource %q not found" (.Get "src") }}
{{ end }}

err := h.Build(BuildCfg{})
if err != nil {
    var fe herrors.FileError
    if errors.As(err, &fe) {
        // fe.Position() gives file:line of the failing shortcode call
    }
    return err
}

When it happens

Trigger: prepareShortcode's render function failing in doRenderShortcode or renderShortcode: the shortcode template panics/errors during execution (nil pointer on .Params, failed function call, type error), a nested shortcode fails, or template lookup/parse of an inline shortcode fails.

Common situations: Shortcode templates referencing missing params (.Get on absent keys used unsafely), errors in partials called from the shortcode, resources.Get failures inside the template, upgrades where template functions changed behavior, errors inside {{% %}} markdown-rendered shortcodes.

Related errors

• %s: shortcode %q does not evaluate .Inner or .InnerDeindent,
• illegal state in content; shortcode token missing end delim
• failed to process shortcode: %w
• render of %q failed: %w
• failed to render shortcode: %w

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