> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Troubleshooting Three checks usually locate the problem: 1. Read the placeholder label: `labels` distinguishes "not evaluated", "blocked", and "unknown structure". 2. Read `document.diagnostics`: each record has `stage`, `code`, and a source position. 3. 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](/guide/introduction.md#default-output) and [syntax support](/guide/syntax-support.md). ## Display | Symptom | Cause | Fix | | ---------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | Template area shows a placeholder | The default pipeline does not evaluate templates | Use [`/expand`](/guide/templates.md), 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 `` | | 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 `` | 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](/guide/syntax-support.md) 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](/guide/server-rendering.md) 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](/api/errors.md) for the full list and class hierarchy. ## Reading diagnostics ```ts 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](/project/contributing.md).