Troubleshooting
Common problems when rendering streamed Typst with typstream, what causes them, and how to fix them.
Start with the document's state: useTypstream() in React, or getState() on a mount. status says where the document is, failure.reason why the latest compile produced nothing, and diagnostics holds Typst's messages. engine.onEvent reports workers that fail to start, crash or hit the watchdog.
Rendering
Check, in this order:
- The worker and the wasm load. In the browser's network panel, look for the worker script,
engine_bg.wasmand the fonts. A 404 means they weren't emitted with your build or aren't served; a bundler that doesn't handlenew URL(…, import.meta.url)needs a worker of your own (Self-hosting). When the engine can't start,engine.onEventreports afailedevent and every document'sfailure.reasonis"engine". - The Content-Security-Policy allows WebAssembly. The page needs
script-src 'wasm-unsafe-eval',worker-src 'self'andconnect-src 'self', and the worker script's own response needs the policy too. The console shows the violation. See Security. - The element is near the viewport. Documents are lazy: one that isn't streaming opens only when its element comes within a screen of the viewport. An element that is hidden (
display: none, a closed tab or accordion) never does. Passlazy={false}(orlazy: falsetomountTypstream) to open it right away.
That is normal. stale means the document is still streaming and the latest prefix didn't compile, so the last good render stays on screen. Most prefixes heal into something that compiles, but some don't until a few more tokens arrive: a half-written argument, a reference to a label defined further down. When the stream ends and isStreaming turns false, the document compiles in final mode and ends as done or error. Show stale as "updating", not as an error. See Streaming.
The watchdog gives each compile 3 seconds while streaming and 10 seconds for the finished document. A compile past its budget is stopped by replacing the worker. After 3 such strikes (timeouts or crashes), live compiling stops for that document and failure.reason is too-complex; the finished document is still compiled once. A streaming paged document with more than 100 pages stops live compiling the same way, and compiles every page when finished.
Usually the document contains a long loop or a huge drawing. If your documents are legitimately heavy, raise the budgets on your engine: createEngine({ spawn: engineWorker(), watchdog: { streamingMs: 5000 }, limits: { livePages: 200 } }), and pass it as engine. See Engine.
Input longer than 1 MiB (1,048,576 UTF-16 code units) isn't healed or compiled, to protect the page. The document keeps its last render and refuses exports until set() or reset() brings the text back under the limit. Raise it with createEngine({ limits: { maxLength } }) if you really need longer documents. @typstream/node's protocol server has its own limit, maxTextLength.
That is the fallback: a block that doesn't compile is shown as an error box with Typst's message and the block's source, and the rest of the document renders around it. The error is in diagnostics. Feed the finished document to @typstream/node's fixLoop to have the model repair it, or improve the prompt for that error class. See Fallback and The server fix loop.
That is by design. <Typstream> compiles in a Web Worker, which only exists in the browser, so on the server it renders an empty <div> and starts after hydration. The typstream and @typstream/react bundles are marked "use client", so Next.js's App Router treats them as client components. If you need the document in the server's HTML (for SEO, or a page without JavaScript), render it on the server with @typstream/node's render(source, "html") (Node.js).
Output looks wrong
MathML needs a math font, and browsers' defaults are poor or missing. html-compat's CSS asks for New Computer Modern Math, which typstream's <Typstream> registers for you. With @typstream/react or @typstream/dom, register it yourself: pass mathFont to <Typstream>, or call registerMathFont(url) from @typstream/dom with the URL from @typstream/engine-wasm/fonts. Under a CSP, font-src 'self' must allow it. See Without a framework.
Typst's HTML export drops layout it can't express, and the content inside it: #grid, #align, #rect, #place, #stack and others come out empty. html-compat maps them to HTML and CSS. typstream's <Typstream> adds it unless you pass htmlCompat={false}; with @typstream/react or @typstream/dom, add htmlCompat to plugins. The html-compat reference lists what it covers and its gaps.
A known gap: fletcher 0.5.8 draws on a CeTZ 0.3.4 canvas that html-compat can't reach, so its diagrams stay empty in HTML. They render in the paged target. CeTZ 0.5 canvases (CeTZ itself, cetz-plot, alchemist) do become SVG in HTML. Use target="paged" for documents with fletcher diagrams, or prompt for CeTZ instead. See Typst packages.
Typst's HTML output has no pages: html-compat writes their settings (headers, footers, numbering, margins, columns) for @typstream/dom's HTML renderer, which lays the pages out. Check that the htmlCompat plugin is loaded (the typstream package loads it) and that you render with <Typstream>, mountTypstream or createHtmlRenderer, not Typst's HTML on its own. See Render targets.
In the paged target and in PDFs, the engine draws these scripts with Noto fonts that it downloads the first time a document needs them, then recompiles. The first render can show boxes for a moment. If they stay, the font download failed: check that the font files are served (network panel), and that the CSP's connect-src allows their origin. A failed font is tried again after 30 seconds.
In the HTML target the browser draws the text, with your page's fonts. Make sure your CSS includes a font for the script, or that readers' systems have one. See Fonts and languages.
CJK fonts aren't included: one weight of Noto Serif SC alone is 11.6 MB. Add the fonts you need through a plugin passed to createEngine, with their metadata so they too load only when used, and give that engine to your components. See Fonts and languages. In the HTML target, the browser's fonts apply.
Documents can import only packages on the engine's allowlist. typstream's <Typstream> allows the vendored ones (CeTZ, fletcher, cetz-plot, physica, unify, chemformula, alchemist); with @typstream/react or @typstream/dom, add the universe plugin. Anything else is reported as package … is not allowed, with the allowed packages as a hint, and nothing is fetched.
is still loading is temporary: a package is downloaded the first time a document imports it, and the document compiles again when it arrives. Meanwhile the names it imports render as placeholders. failed to load (reason) means the tarball couldn't be fetched: check that it is served and that connect-src allows it. See Typst packages.
The model's output
Models fall back to Markdown habits. The healer fixes the common ones in text that has settled: # Heading becomes = Heading, **bold** becomes *bold*, [text](url) becomes a link, and a ```typst fence around the whole document is removed. These are the lint rules markdown-heading, markdown-bold and markdown-link. It can't turn a Markdown document into Typst, though: tell the model to write Typst only. Prompting has the instructions and the prompt kit that measurably lower error rates, and Healing lists every rule.
In Typst, $ starts math, so "costs $5 and $10" becomes an equation. The currency-dollar lint rule spots this and warns by default. To escape such dollars automatically, set it to fix:
<TypstreamProvider heal={{ lint: { "currency-dollar": "fix" } }}>Better still, tell the model to write a literal dollar sign as \$, as the prompts in these docs do.
edu's answers (answer: parameters, #answer[…], #answer-key()) produce output only when sys.inputs.showAnswers is "true". If they show, that input is set somewhere: on a <TypstreamProvider>, which every document below inherits, or in a template's default inputs. Set inputs={{ showAnswers: "true" }} only on the teacher's view. Answers the model writes as plain text, outside edu's functions, are ordinary content and always show; the edu prompt tells the model to use the functions. See Edu documents.
If your problem isn't here, the issue tracker is the place to report it. A fallback event (Telemetry) carries the input and the healed source, which makes a good reproduction.