Troubleshooting

Three checks usually locate the problem:

Read the placeholder label: labels distinguishes "not evaluated", "blocked", and "unknown structure".
Read document.diagnostics: each record has stage, code, and a source position.
Reduce to the smallest source and options; remove custom plugins and components to reproduce.

If you are unsure whether a placeholder is expected, compare it with the default output in the overview and syntax support.

Display

Symptom	Cause	Fix
Template area shows a placeholder	The default pipeline does not evaluate templates	Use `/expand`, or override `semanticComponents.template`
Parser function shows a placeholder	Same; not evaluated by default	Supported pure wikitext functions work through `/expand`; others stay placeholders
Images show only captions	No `resolveImage`, or it returned `null`	Return a validated `src`; enable `allowRelativeImages` for relative URLs
Internal links are not clickable	Default output is non-navigable text	Return `href` from `resolveLink`
External links become plain text	Protocol is not allowlisted	Use `http:`, `https:`, or `mailto:`
HTML becomes a source card	Unknown or unbalanced tag	Check support; custom semantic nodes need `handlers`
Dangerous tags leave only a hint	`script`, `iframe`, etc. are blocked	Expected; do not relax `stripTags` just to display them
A whole table becomes a source card	Nested wikitext table	Flatten the table, or use nested HTML `<table>`
Paragraphs merge	A single newline collapses to a space	Use two blank lines to split
No table of contents	Fewer than four headings, `__NOTOC__`, or `headingIdStrategy: "none"`	Check headings and behavior switches; use `__TOC__` to pin the position
The reference section is not at `<references>`	It is fixed after the body, before categories	Expected; the tag does not control its position
Categories are missing from the body	They are collected into the footer	Expected; label text comes from `labels.categories`
Heading anchors collide	Multiple instances share bare ids	Use the default `instance` strategy, or pass `idPrefix`

See Syntax support for the full default output.

Runtime and build

Symptom	Cause	Fix
`ASYNC_PLUGIN_IN_SYNC_PATH`	Async plugin on the sync path	Use `prepareWikitextAsync`, or prepare outside React
Parsing happens on every render	Inline `parseOptions` / `prepareOptions` objects	Move them out of the component or stabilize with `useMemo`
`PARSER_UNAVAILABLE`	The `wikiparser-node` browser bundle did not initialize `globalThis.Parser`	Ensure the side-effect import runs; avoid duplicate copies or manual dependency pruning
`Cannot find module 'react-wikitext/styles.css'`	CSS not handled by the bundler, or the build lacks `dist/styles.css`	Let the bundler handle package CSS; confirm resolution to `dist/styles.css`
Next.js Server Component throws a `createContext` error	A React entry was called from the server in an environment with RSC boundaries	Confirm the build ships `"use client"`; use server preparation on the server
Hydration mismatch or drifting anchors	Server and client trees differ, or no id prefix is fixed	Render the same tree; pass `idPrefix`; consider the `mediawiki` strategy
Type error: no error classes on the root entry	Error classes are exported per subpath	Import from `/parse`, `/hast`, or `/expand`
CJS environment fails to load	Runtime too old, or bundler ignores `exports`	Use Node `>=18.18` and a bundler that supports conditional exports

Error codes

Errors carry code; prepare errors also carry stage. Never branch on message text.

Code	Stage	Meaning	Action
`SOURCE_TOO_LONG`	Parse	Normalized source exceeds the length budget	Raise `maxSourceLength`, or split the content
`SOURCE_TOO_COMPLEX`	Parse	Node or depth budget exceeded	Raise the relevant budget, or simplify structure
`INVALID_CONFIG`	Parse	Site config or a budget field is invalid	Pass non-negative safe integers
`PARSE_FAILED`	Parse	Upstream parsing or semantic building failed	Keep the source and `cause`, and report it
`PARSER_UNAVAILABLE`	Parse	The default browser bundle did not initialize	Check the build and dependency resolution
`PREPARE_FAILED`	Prepare	Options, plugin, or handler is invalid	Check `policy`, `labels`, `handlers`, and plugin signatures
`ASYNC_PLUGIN_IN_SYNC_PATH`	Prepare	Async plugin on the sync path	Use the async entry
`INVALID_DOCUMENT`	Restore	Snapshot structure, version, or budget is invalid	Restore trusted snapshots only; invalidate old caches
`EXPANSION_TOO_LARGE`	Expand	Expanded output or preserved source is too large	Raise `maxExpandedLength`, or limit template output
`EXPANSION_BUDGET_EXCEEDED`	Expand	Budget exceeded under `strict`	Raise the budget, or turn off `strict` to keep calls
`TEMPLATE_LOOP`	Expand	Loop detected under `strict`	Inspect template dependencies
`ABORTED`	Expand	Cancelled through `signal`	Expected; the original reason is in `cause`

See Errors and diagnostics for the full list and class hierarchy.

Reading diagnostics

for (const diagnostic of prepared.diagnostics) {
  console.warn(diagnostic.stage, diagnostic.code, diagnostic.message);
}

stage can be parse, expand, wikitext, hast, rehype, sanitize, or finalize.
A diagnostic never aborts the whole page; a render failure replaces only the affected top-level block.
View failures are reported through onRenderError; the placeholder title comes from labels.renderFailed.
meta records the effective policy, labels, headingIdStrategy, and authorized images, which helps confirm that config actually applied.

Still stuck

When reporting, include:

The smallest wikitext source and pageName.
Entry, parse options, and prepare options (redacted if needed).
Library version, parserVersion, React, and bundler versions.
document.diagnostics plus the error code, stage, and cause.

More channels are listed in Contributing and feedback.

#Troubleshooting

#Display

#Runtime and build

#Error codes