Troubleshoot

This page is symptom-driven. If you are publishing a demo, start by validating MIME types, CORS, and forge bundle URLs.

Blank page / module failed to load

  • Verify .mjs is served as JavaScript (not text/plain).

  • Confirm the host supports ESM (no HTML rewriting/proxying for .mjs).

Worker fails to load mujoco.wasm

Most common causes:

  • wrong Content-Type for .wasm (must be application/wasm)

  • missing CORS headers when using remote forgeBase=

  • stale/mismatched caching of mujoco.js vs mujoco.wasm (use immutable forge URLs; for debugging append cacheBust=always)

Forge ABI missing exports

If you see an error like:

[forge] Missing viewer ABI exports ...

Your forge bundle is not built with viewer extensions required by Play. Use a compatible forge build (or update the forge commit/version you are pointing at).

Plugin does not load

  • Ensure the plugin is an ESM module and served with a correct JavaScript MIME type.

  • For cross-origin plugin URLs, ensure CORS is enabled.

  • Check console logs for [plugins] load failed.

Performance is unexpectedly slow

  • Browser extensions can significantly affect Worker/WASM timing.

  • Keep the tab in the foreground and disable “efficiency/power saving” modes.

  • Compare localhost vs GitHub Pages; site-level policies may differ.

Strict mode failures

If strict=1 is enabled, caught errors (outside allowlists) will re-throw. Use strict=0 (default) for end-user demos, and enable strict only when debugging/fuzzing.