#Errors and Diagnostics

The library emits two kinds of signals:

• Errors (Error) stop the current call and are thrown; the caller must handle them.
• Diagnostics (WikitextDiagnostic) record a local problem or degradation on the snapshot without aborting the page.

#Error classes

class WikitextError extends Error {
  readonly code: WikitextErrorCode;
  cause?: unknown;
}

class WikitextParseError extends WikitextError {}

class WikitextPrepareError extends WikitextError {
  readonly stage: string;
}

class WikitextExpandError extends WikitextError {
  readonly templateTitle?: string;
  readonly range?: WikitextRange;
}

Every error carries code; cause keeps the underlying error. WikitextPrepareError.stage records the failing stage, commonly prepare, wikitext, rehype, or finalize.

#Exports by entry

#Error codes

In the default mode, expansion preserves calls and records diagnostics; with strict: true, recoverable failures above are thrown.

#Handling examples

import { WikitextParseError } from "react-wikitext/parse";

try {
  const document = parser.parse(source, { pageName: "Example" });
  return document;
} catch (error) {
  if (error instanceof WikitextParseError) {
    if (error.code === "SOURCE_TOO_LONG") {
      return loadSourceInPages(source);
    }
    throw error;
  }
  throw error;
}

import { prepareWikitextAsync, WikitextPrepareError } from "react-wikitext/hast";

try {
  return await prepareWikitextAsync(document, { rehypePlugins });
} catch (error) {
  if (error instanceof WikitextPrepareError) {
    report(error.code, error.stage, error.cause);
  }
  throw error;
}

• Never branch on message text; use code (and stage when relevant).
• Catch parse and prepare errors at the call site and distinguish budgets, config, and plugins.
• Report view failures through onRenderError; the error boundary replaces only the failed top-level block.
• Do not silently fall back to reparsing when restoring a snapshot fails; check the version and the source first.

#Diagnostics

interface WikitextDiagnostic {
  readonly code: string;
  readonly stage: "parse" | "expand" | "wikitext" | "hast" | "rehype" | "sanitize" | "finalize";
  readonly severity: "error" | "warning" | "info";
  readonly message: string;
  readonly position?: WikitextPosition;
  readonly origin?: WikitextOrigin;
  readonly rule?: string;
}

• position and origin refer to the normalized source; generated content may have no origin.
• rule identifies the rule or plugin that produced the record.
• Render snapshot diagnostics merge parse, preparation, and finalization records.
• A single diagnostic never aborts the page; the host decides whether to report or block.

#Related

• Troubleshooting: narrow down by symptom.
• Preparation /hast: prepare-stage and plugin errors.
• Expansion /expand: strict mode and expansion errors.