gohugoio/hugo · error

failed to render shortcode: %w

Error message

failed to render shortcode: %w

What it means

Emitted from contentParseInfo.contentToRender in hugolib/page__content.go when a shortcode that was pre-rendered for a page fails as its output is inlined into the content stream before Goldmark processing. The shortcode's template executed with an error, and Hugo wraps that error to abort rendering of the page.

Source

Thrown at hugolib/page__content.go:249

		case pageparser.Item:
			sm = append(sm, sourceMapEntry{renderOffset: len(c), sourceOffset: v.Pos()})
			c = append(c, source[v.Pos():v.Pos()+len(v.Val(source))]...)
		case pageContentReplacement:
			sm = append(sm, sourceMapEntry{renderOffset: len(c), sourceOffset: v.source.Pos()})
			c = append(c, v.val...)
		case *shortcode:
			sm = append(sm, sourceMapEntry{renderOffset: len(c), sourceOffset: v.pos, isShortcode: true})
			if !v.insertPlaceholder() {
				// Insert the rendered shortcode.
				renderedShortcode, found := renderedShortcodes[v.placeholder]
				if !found {
					// This should never happen.
					panic(fmt.Sprintf("rendered shortcode %q not found", v.placeholder))
				}

				b, more, err := renderedShortcode.renderShortcode(ctx)
				if err != nil {
					return nil, nil, false, fmt.Errorf("failed to render shortcode: %w", err)
				}
				hasVariants = hasVariants || more
				c = append(c, []byte(b)...)

			} else {
				// Insert the placeholder so we can insert the content after
				// markdown processing.
				c = append(c, []byte(v.placeholder)...)
			}
		default:
			panic(fmt.Sprintf("unknown item type %T", it))
		}
	}

	return c, sm, hasVariants, nil
}

func (c *cachedContent) IsZero() bool {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Inspect the wrapped error — it includes the shortcode name, file, and line of the failing template action.
2. Fix the shortcode call in the content file (add missing named/positional params) or harden the shortcode template with `{{ with ... }}` guards.
3. If it's a theme shortcode, override it in layouts/_shortcodes/ (or layouts/shortcodes/ in older versions) with a corrected copy.
4. Run `hugo --logLevel debug` to see which page and shortcode invocation triggers it.

Example fix

{{/* layouts/_shortcodes/img.html before */}}
<img src="{{ (.Page.Resources.Get (.Get 0)).RelPermalink }}">
{{/* after */}}
{{ with .Page.Resources.Get (.Get 0) }}<img src="{{ .RelPermalink }}">{{ else }}{{ errorf "img shortcode: resource %q not found in %s" (.Get 0) .Page.File.Path }}{{ end }}

// confirm the shortcode template exists before authoring content that uses it
// ls layouts/_shortcodes/myshortcode.html

content, err := p.Content(ctx)
if err != nil {
    // error already wraps file position of the failing shortcode
    return fmt.Errorf("page %s: %w", p.Path(), err)
}

When it happens

Trigger: Building a site where a page contains a `{{< shortcode >}}` whose template errors at render time: undefined method on .Params, failing resources.Get/GetRemote inside the shortcode, `errorf` called in the shortcode template, or a nested inner shortcode failing.

Common situations: Theme shortcodes that expect parameters the content author omitted; shortcodes fetching remote resources that 404 or time out; Hugo version upgrades removing template functions a shortcode used; shortcodes referencing page resources that don't exist in the bundle.

Related errors

• failed to render shortcode %q: %w
• illegal state in content; shortcode token missing end delim
• unknown shortcode token %q (number of tokens: %d)
• %v failed to render pages: %w
• error building site: %w

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