DioxusLabs/dioxus · error

should have a document on window

Error message

should have a document on window

What it means

`append_element_to_head` gets the global window and `expect`s a document to exist on it. This panic fires when running outside a proper browser context where `window.document()` returns None — e.g. a headless/fragmented web context — while trying to add meta/script/style/link elements to the head.

Source

Thrown at packages/web/src/document.rs:173

            );
        });
    }

    /// Create a new link tag in the head
    fn create_link(&self, props: LinkProps) {
        queue_effect(move || {
            _ = append_element_to_head("link", &props.attributes(), None);
        });
    }
}

fn append_element_to_head(
    local_name: &str,
    attributes: &Vec<(&'static str, String)>,
    text_content: Option<&str>,
) -> Result<(), JsValue> {
    let window = web_sys::window().expect("no global `window` exists");
    let document = window.document().expect("should have a document on window");
    let head = document.head().expect("document should have a head");

    let element = document.create_element(local_name)?;
    for (name, value) in attributes {
        element.set_attribute(name, value)?;
    }
    if text_content.is_some() {
        element.set_text_content(text_content);
    }
    head.append_child(&element)?;

    Ok(())
}

/// Required to avoid blocking the Rust WASM thread.
const PROMISE_WRAPPER: &str = r#"
    return (async function(){
        {JS_CODE}

View on GitHub (pinned to 24f6a829df)

Solutions

1. Ensure the code runs in a browser context where `window.document` is available; guard against non-web targets.

When it happens

Trigger: Thrown at packages/web/src/document.rs:173 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of DioxusLabs/dioxus@24f6a829df (2026-08-23). Data as JSON: /api/errors/e864ed0ba3f9ad8e. Report an issue: GitHub.