gohugoio/hugo · critical

rendered shortcode %q not found

Error message

rendered shortcode %q not found

What it means

Panic during content assembly: a shortcode placeholder recorded in the source map is not present in the renderedShortcodes map. The inline comment says 'This should never happen', marking it an internal invariant failure in shortcode rendering bookkeeping. The rendered-shortcode map should always contain every placeholder written into the source.

Source

Thrown at hugolib/page__content.go:244

	c := make([]byte, 0, len(source)+(len(source)/10))
	var sm []sourceMapEntry

	for _, it := range pi.itemsStep2 {
		switch v := it.(type) {
		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))
		}
	}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Clean-rebuild (clear public/, resources/_gen, build lock) to discard stale shortcode state.
2. Simplify the failing shortcode (reduce nesting / deferred content) to isolate the bug.
3. Upgrade Hugo; report the placeholder and shortcode template if it reproduces.

Example fix

# before
hugo  # incremental build hits stale shortcode placeholder

# after
rm -rf public resources/_gen .hugo_build.lock && hugo

// Not directly preventable by API users — internal invariant.
// Mitigate: clean-rebuild (rm -rf public resources/_gen .hugo_build.lock && hugo)
// and simplify nested/deferred shortcodes.

// Wrap Build in recover() to surface the placeholder cleanly (see 781).

When it happens

Trigger: The renderedShortcodes map is populated during shortcode rendering but a placeholder written by the parser is missing from it — caused by a mismatch between shortcode parsing and rendering passes, concurrent map mutation, or an incremental build that retained stale placeholders. Usually an internal bug.

Common situations: Complex nested shortcodes, shortcodes that produce variants/deferred content, incremental builds with stale shortcode state. A Hugo version change in the shortcode protocol with leftover cache.

Related errors

• unknown item type %T
• ContentMediaType not set
• no pageOutput
• pageOutput is nil for output idx %d
• pageMeta.pageMetaSource.pi must be set before creating cache

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