{"record":{"id":"257e733795d087e6","repo":"emilk/egui","slug":"the-surface-isn-t-supported-by-this-adapter","errorCode":null,"errorMessage":"The surface isn't supported by this adapter","messagePattern":"The surface isn't supported by this adapter","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/egui-wgpu/src/winit.rs","lineNumber":120,"sourceCode":"        let desired_maximum_frame_latency = if surface_state.resizing {\n            Some(desired_maximum_frame_latency.unwrap_or(2).max(2))\n        } else {\n            desired_maximum_frame_latency\n        };\n\n        let width = surface_state.width;\n        let height = surface_state.height;\n\n        let mut surf_config = wgpu::SurfaceConfiguration {\n            usage: wgpu::TextureUsages::RENDER_ATTACHMENT,\n            format: render_state.target_format,\n            present_mode,\n            alpha_mode: surface_state.alpha_mode,\n            view_formats: vec![render_state.target_format],\n            ..surface_state\n                .surface\n                .get_default_config(&render_state.adapter, width, height)\n                .expect(\"The surface isn't supported by this adapter\")\n        };\n\n        if let Some(desired_maximum_frame_latency) = desired_maximum_frame_latency {\n            surf_config.desired_maximum_frame_latency = desired_maximum_frame_latency;\n        }\n\n        surface_state\n            .surface\n            .configure(&render_state.device, &surf_config);\n    }\n\n    /// Drop the existing [`wgpu::Surface`] for `viewport_id` and create a fresh one for the\n    /// given window via [`wgpu::Instance::create_surface`], then configure it.\n    ///\n    /// Used to recover from [`wgpu::CurrentSurfaceTexture::Lost`], where reconfiguring the\n    /// existing surface object cannot recover.\n    fn recreate_surface(\n        &mut self,","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/emilk/egui/blob/8fb03c9ae9a6bf1ffa602dfba51ed575f2655975/crates/egui-wgpu/src/winit.rs#L102-L138","documentation":"During surface configuration, egui-wgpu calls surface.get_default_config(adapter, width, height) and expects Some; the expect panics with \"The surface isn't supported by this adapter\" when wgpu cannot produce a default configuration. This means the adapter cannot render to the given surface at all — typically the surface's target display/plane is not usable by the selected adapter — so no valid SurfaceConfiguration (usage/format present mode etc.) exists and rendering to this window is impossible with this adapter.","triggerScenarios":"Configuring a surface on an adapter that doesn't support it: e.g. a window on a different GPU than the one wgpu picked, headless/offscreen environments where the surface has no display, virtual machines / remote desktops without present support, or adapters from a backend (e.g. GL) that can't drive the window system surface. Also surfaces created for a window that was closed or not yet visible on some platforms.","commonSituations":"Hybrid laptops (NVIDIA Optimus) where the app runs on the discrete GPU while the window belongs to the iGPU display; running in WSL, SSH X-forwarding, VMs or Wayland-less containers; multi-monitor setups where the window is moved to a monitor the adapter can't present to; picking a specific adapter (power_preference/pick_adapter) that doesn't own the display.","solutions":["Create the wgpu adapter and the surface compatibly: obtain the adapter via instance.request_adapter with compatible_surface: Some(&surface) so the chosen adapter supports the window.","On hybrid GPUs, iterate request_adapter options and pick an adapter whose get_default_config for the surface is Some, falling back to another backend (e.g. GL) otherwise.","Check the environment: run natively instead of via RDP/X-forwarding/VM, or use a software/llvmpipe adapter when no display GPU is available.","Before configuring, guard the call: match on get_default_config yourself and show a graceful error instead of panicking inside the egui-wgpu render loop.","Ensure the window is valid and shown before creating/configuring the surface."],"exampleFix":"// before: adapter chosen without surface compatibility\nlet adapter = instance.request_adapter(&RequestAdapterOptions { power_preference: HighPerformance, ..Default::default() }).await.unwrap();\n// ... later: egui_wgpu panics: surface isn't supported by this adapter\n// after: request an adapter compatible with the surface\nlet adapter = instance\n    .request_adapter(&wgpu::RequestAdapterOptions {\n        power_preference: wgpu::PowerPreference::HighPerformance,\n        compatible_surface: Some(&surface),\n        force_fallback_adapter: false,\n    })\n    .await\n    .expect(\"no adapter that supports this surface\");","handlingStrategy":"validation","validationCode":"// Rust: verify surface/adapter compatibility before letting egui-wgpu configure\nif surface.get_default_config(&adapter, width, height).is_none() {\n    eprintln!(\"surface not supported by this adapter; requesting a compatible adapter\");\n    // re-request adapter with compatible_surface: Some(&surface)\n}","typeGuard":"fn supports_surface(instance: &wgpu::Instance, adapter: &wgpu::Adapter, surface: &wgpu::Surface<'_>, w: u32, h: u32) -> bool {\n    surface.get_default_config(adapter, w, h).is_some()\n}","tryCatchPattern":"// wgpu surfaces return errors as device callbacks; install a scope that captures them\nlet err_scope = wgpu::util::initialize_adapter_from_env_or_default(...) /* and */\n// capture panics/lost-config errors at app level:\nstd::panic::catch_unwind(std::panic::AssertUnwindSafe(|| renderer.draw(...)))\n    .or_else(|_| show_fallback_message(\"GPU cannot present to this window\"))","preventionTips":["Always request the adapter with compatible_surface: Some(&surface).","Test on hybrid-GPU laptops, VMs and remote-desktop environments before shipping.","Guard get_default_config yourself and degrade gracefully instead of panicking in the render loop."],"tags":["wgpu","gpu","surface-configuration","adapter-compatibility"],"backgroundTag":"unsupported-operation","analyzedSha":"8fb03c9ae9a6bf1ffa602dfba51ed575f2655975","analyzedAt":"2026-09-12T04:29:21.500Z","contentChangedAt":"2026-09-12T04:29:21.500Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}