Troubleshooting

This page collects the most common issues seen while working with the viewer, embed artifacts, and Sphinx integration.

Frontend Build Not Found

If the Python server returns a 503 with a message about a missing frontend build, run:

npm install
npm run build:site

The local server expects the built site in dist/site.

Embed Changes Do Not Show Up In Docs

If Sphinx pages still show old behavior after frontend changes:

npm run build:embed
python3 -m sphinx -E -a -b html docs docs/_build/html

The important part is rebuilding both:

  • the embed artifact

  • the Sphinx HTML pages that inline it

Opening Non-Self-Contained HTML Over file://

Normal Vite production output is not meant to be opened directly from file:// because browsers will block asset loading.

Use one of these instead:

  • dist/site through HTTP

  • dist/embed/jsonschema-diagram.embed.html for standalone embed viewing

Sphinx Theme Not Found

If Sphinx reports that the furo theme cannot be found, install docs dependencies:

python3 -m pip install -r docs/requirements.txt

Clipboard Paste Does Not Work

Clipboard access in the editor depends on browser capabilities and origin security rules. If paste from the toolbar fails:

  • use a secure origin or local dev server

  • paste manually into the raw schema editor

Huge Bundle Warning During Build

The current frontend bundle is still large enough to trigger Vite’s chunk-size warning. This is not a functional error, but it is useful to know when tuning performance.

If you see the warning:

  • the build still succeeded

  • runtime behavior is still valid

  • future optimization can focus on chunk splitting and lazy loading

Broken Or Stale Theme In Embed

If the wrong embed theme shows up:

  • check defaultTheme in window.__JSONSCHEMA_DIAGRAM_CONFIG__

  • check default_theme in the Jinja2 render context

  • rebuild embed output after changing frontend theme presets

Pattern Property Paths Look Surprising

For patternProperties, JSON path uses a generated sample key, not the regex itself. That is intentional because the path aims to look like instance data.

Combinator Branch Paths Use [*]

If a selected node is the direct root of an anyOf or oneOf branch, the JSON path may use [*] instead of a concrete array index or property name. That means the schema branch describes the same instance slot as sibling branches, so a single concrete location would be misleading.