Troubleshooting

Start with the exact error and the smallest document that reproduces it. Run validate(document) before rendering; each issue includes the failing path, a stable code, a severity, and a suggested fix.

Installation fails on workspace:*

Install the published package, not a tarball copied directly from the Runstamp monorepo:

pnpm add @runstamp/react @runstamp/pptx react react-dom

Published packages replace internal workspace:* ranges during packing. If a registry tarball still contains one, capture pnpm view @runstamp/react version, your lockfile entry, and the full install error, then report it as a packaging bug. Contributors working inside this repository should run pnpm install from the repository root.

The deck works in LibreOffice but PowerPoint repairs it

LibreOffice is useful for a quick visual check, but it is not the compatibility authority for .pptx. Validate the generated file in desktop Microsoft PowerPoint on Windows or macOS. A clean LibreOffice open does not prove PowerPoint will accept chart XML, relationships, embedded media, or content types.

If PowerPoint shows a repair prompt:

1. Keep the original generated file; do not save over it.
2. Record the Runstamp package versions and operating system.
3. Reduce the input while preserving the prompt.
4. Attach PowerPoint's repair log and the reduced input to the bug report.

Do not suppress validation errors or use LibreOffice success as a release gate.

A brand-pack .potx is not applied locally

A .potx file is a PowerPoint template, not a theme token object. The open-source local compiler accepts declarative content and Runstamp tokens; it does not silently import an arbitrary .potx.

Use one of these paths:

• Convert the brand's palette and typography to the declarative document's token contract.
• Use a hosted brand pack and reference its brandPackId or brandPackVersionId where that API is enabled.
• For a custom template workflow, verify the template in desktop PowerPoint and use the package/API documented for template rendering.

Do not rename .pptx to .potx, or assume fonts embedded in a template are installed on the render host.

Fonts look different between preview and PowerPoint

The React viewer uses fonts available in the browser. PowerPoint uses fonts available on the machine opening the deck unless the file embeds compatible fonts. Load the same web fonts for the viewer, call autoLoadDocumentFonts(document) before local PPTX rendering, and test the exported file on a machine with the intended fonts.

React components fail during server rendering

Import the stylesheet once in your application entry point. Render the interactive viewer from a Client Component, but keep file generation in a Node.js server route using @runstamp/react/server. Do not call browser-only download behavior during server render.

For Next.js Route Handlers, set:

export const runtime = "nodejs";

validate() returns warnings but ok is true

ok means there are no error-severity issues. Warnings still describe quality or compatibility risks worth fixing before distribution. Treat errors as render blockers and decide explicitly whether your workflow permits each warning code.

The downloaded file is empty or named incorrectly

Return the renderer's bytes without JSON encoding them and use the PPTX content type:

application/vnd.openxmlformats-officedocument.presentationml.presentation

Set Content-Disposition to an attachment ending in .pptx. In Node.js, preserve the returned Uint8Array or Buffer; do not convert it through UTF-8 text.

Still blocked

Include a minimal input document, exact package versions, runtime version, target Office application/version, validation issues, and the smallest generated file that reproduces the failure. Remove confidential content before sharing.