gohugoio/hugo · critical

unknown item type %T

Error message

unknown item type %T

What it means

Panic in the content source-map assembly loop: an item 'it' in the parsed content items is neither a pageparser.Item, a pageContentReplacement, nor a *shortcode. The switch's default branch panics with the item's Go type, indicating an unexpected item type reached the assembler — an internal invariant failure in the page parser pipeline.

Source

Thrown at hugolib/page__content.go:260

				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 {
	return len(c.pi.itemsStep2) == 0
}

func (pi *contentParseInfo) parseSource(source []byte, skipFrontMatter bool) error {
	if len(pi.itemsStep1) == 0 {
		return nil
	}

	s := pi.shortcodeParseInfo

	fail := func(err error, i pageparser.Item) error {

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Upgrade Hugo to a release where parser and assembler are consistent.
2. If hit, capture the %T type from the panic and report a Hugo issue with the content file.
3. Clean-rebuild to rule out stale parsed content.
4. If forking, add the new item type to the switch in page__content.go around line 230.

Example fix

// before (fork): new item type unhandled
case pageparser.Item: ...
default: panic("unknown item type %T")

// after: handle the new type
case myCustomItem:
    sm = append(sm, ...)
case pageparser.Item: ...

// Internal invariant — parser/assembler type mismatch.
// Mitigate: upgrade Hugo; clean-rebuild; capture the %T type from the panic for the bug report.

// Wrap Build in recover() to capture the item type (see 781).

When it happens

Trigger: The page parser emitted an item of a type the assembler does not handle. Caused by an internal change to the parser item types that did not update the assembler's type switch, or by injecting a non-standard item into the items slice (fork). Reachable only via internal bugs.

Common situations: Hugo version mismatch between parser and assembler. A fork adding new item types without updating the switch. A corrupted/edge-case content file that the parser mishandles.

Related errors

• pageMeta.pageMetaSource.pi must be set before creating cache
• rendered shortcode %q not found
• ContentMediaType not set
• no pageOutput
• pageOutput is nil for output idx %d

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