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

Use the wrapped %w to get the template/function name and line that failed.

failed to render shortcode

Error message

failed to render shortcode: %w

What it means

Emitted during the second content-assembly pass (page__content.go:249) when rendering an already-parsed shortcode into HTML fails. The %w carries the concrete shortcode-render error (template execution failure, nested-shortcode error, or a function-call error inside the shortcode template).

Solutions

Use the wrapped %w to get the template/function name and line that failed.
Open the named shortcode template (layouts/shortcodes/*.html) and fix the reported call.
Verify any partial the shortcode includes exists and renders standalone.
Check the parameters passed in the page content match what the shortcode expects.

Example fix

// before
{{< myshortcode badparam >}}

// after: correct the parameter the shortcode template errors on
{{< myshortcode param="value" >}}

Defensive patterns

Strategy: try-catch

Validate before calling

# lint shortcode references resolve before building
grep -rhoE '\{\{<[^>]+>\}\}' content/ | sort -u   # then check each name exists under layouts/shortcodes/

Try / catch

{{ with try (templates.Execute (dict)) }}{{ . }}{{ else }}{{ errorf "shortcode failed: %s" . }}{{ end }}

Prevention

Keep shortcode templates self-contained; verify partials they include exist.
Validate shortcode parameter names match the template.
Use `errorf` in shortcode templates to fail loudly with context instead of panicking.

When it happens

Trigger: A shortcode template executes an undefined function, references a missing partial, divides by zero, calls a method that errors, or nests a shortcode whose own render fails. The failure happens while expanding the renderedShortcode into the page's content byte stream.

Common situations: Typo in a shortcode parameter/function name; a shortcode partial deleted but still referenced; a shortcode that worked in one Hugo version but uses a changed/removed API; data fed to a shortcode that violates an assertion.

Related errors

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

Appendix: 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 52c9bd7908)