Debugging and limits
Most failures fall into one of four buckets: invalid Mermaid source, missing fonts, export constraints, or host-side lifecycle timing
Render failures
The runtime shows a compact fallback when Mermaid parsing fails
Checklist
- Confirm the fence actually starts with
mermaid - Confirm the source is valid Mermaid syntax for the chosen diagram type
- Confirm Excalidraw mode is not being used as a parser substitute for custom DSLs
Missing or wrong fonts
Font problems are almost always host-side problems
- Confirm the stylesheet or
@font-facedeclarations load before rendering - Confirm the configured family string matches the loaded family name exactly
- Confirm mixed-script diagrams use a fallback chain only when that fallback is really needed
Export limits
PNG export protects the browser from extreme canvas sizes
- Minimum export scale: 2
- Maximum bitmap edge: 8192 px
- Maximum pixel budget: about 16 million pixels
Large diagrams still export well, but the scale may be reduced to stay inside browser limits
Route-related issues
VitePress pages can still race the DOM if custom layouts delay wrapper insertion beyond the normal retry window
The first lever is waitFor: 'animation-frame'
The second lever is a scoped root option that narrows rendering to the actual docs container