Troubleshooting

Model download fails

Confirm Hugging Face is reachable, or set modelBaseURL to a CORS-enabled mirror. Call redownloadModel() after an interrupted download.

Browser playback is blocked

Autoplay policies may require a click or tap. Generate at any time, then call play() from a user gesture.

The page appears frozen

ONNX inference is CPU-heavy. Set visible state before awaiting setup or generation. Use stream() so the browser can paint between sentence results, and avoid synthesizing large documents in one call.

WASM backend fails

Reload after SDK upgrades. Make self-hosted ONNX Runtime Web assets match the installed package version, and inspect Content Security Policy for blocked scripts, modules, workers, or WASM.

Node cannot load a path

Path-based modelFiles work in Node. Browsers need bytes, custom storage, or fetchable URLs.

Emscripten is missing during build

The phonemizer build needs emcc. Install Emscripten and verify emcc --version, or set EMCC to the compiler path.

Cache disappears on refresh

file:// uses memory fallback. Serve the app from HTTP(S) for Cache API behavior, or provide custom storage.

Include runtime, browser or Node version, model, storage configuration, and the complete error in reports: Web SDK issues.