slint-ui/slint · critical

wasm-interpreter: Could not retrieve DOM document

Error message

wasm-interpreter: Could not retrieve DOM document

What it means

The wasm-interpreter crate's `init` function calls `web_sys::window().document()`, which returns None when the wasm code is not running in a browser context that exposes a DOM document. The library panics because `init` must bind to an HTML canvas element that only exists in a web page's DOM. This happens when the compiled wasm runs outside a browser, or in workers/iframes without document access.

Solutions

1. Only call init() from the main browser thread where `window` and `document` are available; do the init from JS glue loaded into a real page.
2. If using a worker, proxy canvas/UI initialization to the main thread via postMessage and only call Slint APIs there.
3. For headless testing, use a DOM-emulating runner (e.g. wasm-bindgen-test with a browser runner) instead of Node.
4. Check `web_sys::window().and_then(|w| w.document()).is_some()` before calling init and skip or route init accordingly.

Example fix

// before (worker or Node test)
slint_interpreter::init(); // panics: no DOM document

// after: guard on browser context
if web_sys::window().and_then(|w| w.document()).is_some() {
    slint_interpreter::init();
} else {
    // defer to main thread / browser-only path
}

const has_dom = () => typeof web_sys::window === 'function' && web_sys::window().map(|w| w.document().is_some()).unwrap_or(false);
if (!has_dom()) { /* route init to main thread or skip */ }

fn has_dom_document() -> bool {
    web_sys::window().and_then(|w| w.document()).is_some()
}

When it happens

Trigger: Calling `slint_interpreter::init()` (or the generated JS entry point that calls it) in a WebAssembly context where `window().document()` returns None: running in a web worker, service worker, Node.js wasm runtime, or a headless/non-browser embedding.

Common situations: Running unit tests for the wasm crate under Node.js or wasm-bindgen-test in a non-DOM runner; embedding the interpreter wasm in a server-side or CLI context; initializing from a worker thread instead of the main browser thread; loading the module before the page DOM is available.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• wasm-interpreter: Could not retrieve DOM window
• Cannot proceed without WebGL - aborting
• wasm-interpreter: Could not retrieve existing HTML Canvas…
• winit backend: Specified DOM element
• Callbacks were set up earlier

AI-assisted analysis of slint-ui/slint@bb937076de (2026-09-16). Data as JSON: /api/errors/5976637a8c3c4bfe. Report an issue: GitHub.

Appendix: source

Thrown at api/wasm-interpreter/src/lib.rs:389

);

#[wasm_bindgen(start)]
pub fn init() -> Result<(), JsValue> {
    #[cfg(feature = "console_error_panic_hook")]
    console_error_panic_hook::set_once();
    let backend = i_slint_backend_winit::Backend::builder()
        .with_spawn_event_loop(true)
        .with_window_attributes_hook(|mut attrs| {
            NEXT_CANVAS_ID.with(|next_id| {
                if let Some(canvas_id) = next_id.borrow_mut().take() {
                    use i_slint_backend_winit::winit::platform::web::WindowAttributesExtWebSys;

                    use wasm_bindgen::JsCast;

                    let html_canvas = web_sys::window()
                        .expect("wasm-interpreter: Could not retrieve DOM window")
                        .document()
                        .expect("wasm-interpreter: Could not retrieve DOM document")
                        .get_element_by_id(&canvas_id)
                        .unwrap_or_else(|| {
                            panic!(
                                "wasm-interpreter: Could not retrieve existing HTML Canvas element '{}'",
                                canvas_id
                            )
                        })
                        .dyn_into::<web_sys::HtmlCanvasElement>()
                        .unwrap_or_else(|_| {
                            panic!(
                                "winit backend: Specified DOM element '{}' is not a HTML Canvas",
                                canvas_id
                            )
                        });
                    attrs = attrs
                        .with_canvas(Some(html_canvas))
                        // Don't activate the window by default, as that will cause the page to scroll,
                        // ignoring any existing anchors.

View on GitHub (pinned to bb937076de)