Troubleshooting

Start with the error class and the document diagnostics. Public wrapper errors include stable codes.

Rendering requires a browser#

UnsupportedEnvironmentError means the render call ran without the required browser APIs.

In Next.js, move the call into a client component event or effect. Importing the package is not the same as calling the renderer.

A ref is null#

InvalidSourceError can mean the ref has not mounted.

if (!reportRef.current) return;
const pdf = await renderPdf(reportRef);

Do not start the render during the component render phase.

A resource failed to load#

ResourceLoadError identifies an image, stylesheet, canvas, or SVG resource that could not be materialized.

Check these values:

• baseUrl
• browser CORS rules
• authentication headers
• resourceResolver
• resourcePolicy

Unsupported CSS rejected the render#

UnsupportedCssError is expected when the selected policy is error and the snapshot contains unsupported input.

Inspect the CSS support matrix. Remove the property, choose a supported layout, or use unsupportedCss: "warn" when a warning is acceptable.

Worker startup fails#

The default backend uses a Worker. If the environment has WebAssembly but cannot start that Worker, create a main-thread renderer.

const renderer = await createRenderer({ execution: "main" });

Main-thread WebAssembly work can block the UI. Treat this as a fallback.

WASM render failure#

WasmRenderError exposes a numeric status. Record the status, error code, and related diagnostics before reducing the input to a small reproduction.

The PDF is blank or clipped#

Check the page geometry and root width first.

• Do not duplicate margins.
• Avoid fixed page-height simulations.
• Remove overflow: hidden from content that must fragment.
• Set a deterministic viewport for responsive layouts.
• Use layoutContext: "page" when the root should size against the PDF content box.

PDF/A or attachment export fails#

First check source availability. The published 0.2.0 package predates these options; the JavaScript bindings and WASM must come from the same PDF/A-capable build.

WasmRenderError with status -4 can indicate invalid conformance or attachment options. Use "pdfa-3u", unique nonempty filenames, ArrayBuffer or Uint8Array data, a MIME type without parameters, a supported relationship, and a valid optional Date.

For native archival failures, check the error message for CMYK JPEGs, missing glyphs, font embedding restrictions, or serialization limits. Correct the resource and render again. The renderer does not downgrade a failed archival request to ordinary PDF.

Validate the final downloaded file with veraPDF. A successful preview does not establish conformance. See PDF/A-3 compliance.