Couldn't get the window handle in time for renderer initiali

Error message

Couldn't get the window handle in time for renderer initialization

What it means

During renderer initialization Bevy locks the mutex guarding the primary window's raw-handle wrapper and expects the lock to succeed. std Mutex::lock() only returns Err when the mutex is poisoned — another thread panicked while holding this exact lock. This panic is therefore a secondary symptom: the real failure is an earlier panic on the thread that held the window-handle lock.

Source

Thrown at crates/bevy_render/src/renderer/mod.rs:246

        },
    };

    #[cfg(not(feature = "raw_vulkan_init"))]
    let instance = Instance::new(instance_descriptor);
    #[cfg(feature = "raw_vulkan_init")]
    let mut additional_vulkan_features = raw_vulkan_init::AdditionalVulkanFeatures::default();
    #[cfg(feature = "raw_vulkan_init")]
    let instance = raw_vulkan_init::create_raw_vulkan_instance(
        instance_descriptor,
        &raw_vulkan_init_settings,
        &mut additional_vulkan_features,
    );

    let surface = primary_window.and_then(|wrapper| {
        let maybe_handle = wrapper
            .0
            .lock()
            .expect("Couldn't get the window handle in time for renderer initialization");
        if let Some(wrapper) = maybe_handle.as_ref() {
            // SAFETY: Plugins should be set up on the main thread.
            let handle = unsafe { wrapper.get_handle() };
            Some(
                instance
                    .create_surface(handle)
                    .expect("Failed to create wgpu surface"),
            )
        } else {
            None
        }
    });

    let force_fallback_adapter = std::env::var("WGPU_FORCE_FALLBACK_ADAPTER")
        .map_or(options.force_fallback_adapter, |v| {
            !(v.is_empty() || v == "0" || v == "false")
        });

View on GitHub (pinned to 396ca72708)

Solutions

Scroll up in the logs and find the FIRST panic — fix that root cause; this expect is only collateral damage
Reproduce the earlier panic with RUST_BACKTRACE=1 to identify which thread held the handle lock
Audit custom code that takes the window handle across threads and ensure it cannot panic while holding the lock

Defensive patterns

Strategy: validation

Validate before calling

// If you share the handle wrapper in custom code:
if my_handle_mutex.is_poisoned() {
    // an earlier panic holds the lock; fix that root cause before renderer init
    eprintln!("window handle lock poisoned by an earlier panic");
}

Prevention

Always read the FIRST panic in the log — this expect is downstream collateral damage
Run with RUST_BACKTRACE=1 during startup to identify the thread that poisoned the lock
Avoid panicking while holding locks around window handles in custom plugins

When it happens

Trigger: Any prior panic on another thread while it held the lock around the window's RawHandleWrapper (for example a panic during surface creation, wgpu error handling, or app setup that had taken the handle), followed by renderer init trying to lock it.

Common situations: A panicking render/setup thread that surfaced the handle before failing; nested panic chains during startup; logs that show an earlier unrelated panic right before this one; multithreaded window-handle sharing in custom plugins.

Related errors

AI-assisted analysis of bevyengine/bevy@396ca72708 (2026-08-20). Data as JSON: /api/errors/418cae63a35b4fc0. Report an issue: GitHub.