{"record":{"id":"93381dedd73e86ef","repo":"GraphiteEditor/Graphite","slug":"failed-to-create-wgpu-context","errorCode":null,"errorMessage":"Failed to create WGPU context","messagePattern":"Failed to create WGPU context","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"desktop/src/gpu_context.rs","lineNumber":15,"sourceCode":"use crate::wrapper::{WgpuContext, WgpuContextBuilder, WgpuFeatures};\n\npub(super) async fn create_wgpu_context() -> WgpuContext {\n\tlet mut wgpu_context_builder = WgpuContextBuilder::new().with_features(WgpuFeatures::IMMEDIATES);\n\n\t// TODO: make this configurable via cli flags instead\n\tif let Some(index) = std::env::var(\"GRAPHITE_WGPU_ADAPTER\").ok().and_then(|s| s.parse().ok()) {\n\t\ttracing::info!(\"Overriding WGPU adapter selection with adapter index {index}\");\n\t\twgpu_context_builder = wgpu_context_builder.with_selection(index);\n\t}\n\n\t// TODO: add a cli flag to list adapters and exit instead of always printing\n\tprintln!(\"\\nAvailable WGPU adapters:\\n{}\", wgpu_context_builder.available_adapters_fmt().await);\n\n\tlet wgpu_context = wgpu_context_builder.build().await.expect(\"Failed to create WGPU context\");\n\n\t// TODO: add a cli flag to list adapters and exit instead of always printing\n\tprintln!(\"Using WGPU adapter: {:?}\", wgpu_context.adapter.get_info());\n\n\twgpu_context\n}\n","sourceCodeStart":1,"sourceCodeEnd":22,"githubUrl":"https://github.com/GraphiteEditor/Graphite/blob/c507b356453361e31638b8bff8f6d46b6da2961e/desktop/src/gpu_context.rs#L1-L22","documentation":"Panic when WgpuContextBuilder::build() returns None, meaning wgpu could not acquire a GPU adapter/device satisfying the requested configuration (features include WgpuFeatures::IMMEDIATES, plus an optional adapter-index override from GRAPHITE_WGPU_ADAPTER). The builder returns None when request_adapter finds no compatible adapter for any backend, the chosen index does not exist, or the subsequent device request is denied because the adapter lacks the required features.","triggerScenarios":"Linux without Vulkan drivers installed (no ICDs, so no adapter enumerates); running in a VM or over remote desktop without GPU acceleration; GRAPHITE_WGPU_ADAPTER set to an out-of-range index; a GPU/driver combination that does not expose the IMMEDIATES feature; GPU out of memory during device creation.","commonSituations":"Fresh Linux installs missing mesa-vulkan-drivers or vulkan-radeon/nvidia ICDs; software-rendered VMs (llvmpipe without required features); stale proprietary drivers after a kernel upgrade; users copying a GRAPHITE_WGPU_ADAPTER index between machines with different adapter orders.","solutions":["Read the 'Available WGPU adapters:' list the app prints just before the panic to confirm what wgpu can see","On Linux install Vulkan drivers (mesa-vulkan-drivers / vulkan-radeon / proprietary NVIDIA ICD) and verify with vulkaninfo","Unset GRAPHITE_WGPU_ADAPTER or set it to a valid index from the printed list","In VMs enable 3D acceleration, or update the GPU driver on the host/Windows machine"],"exampleFix":"# before (shell)\nGRAPHITE_WGPU_ADAPTER=9 ./graphite  # panics: Failed to create WGPU context\n\n# after\nunset GRAPHITE_WGPU_ADAPTER\nvulkaninfo --summary  # verify an ICD is present\n./graphite","handlingStrategy":"try-catch","validationCode":"// Enumerate adapters first and confirm a candidate exists before building the context\nlet adapters = wgpu_context_builder.available_adapters_fmt().await;\nif adapters.trim().is_empty() {\n\teprintln!(\"no WGPU adapters found; install Vulkan/GL drivers before launching\");\n\tstd::process::exit(1);\n}","typeGuard":null,"tryCatchPattern":"let Some(wgpu_context) = wgpu_context_builder.build().await else {\n\teprintln!(\"Failed to create WGPU context. Available adapters:\\n{}\", wgpu_context_builder.available_adapters_fmt().await);\n\teprintln!(\"Install Vulkan drivers or unset GRAPHITE_WGPU_ADAPTER and retry.\");\n\tstd::process::exit(1);\n};","preventionTips":["Verify a working Vulkan stack with vulkaninfo before launching on Linux","Treat GRAPHITE_WGPU_ADAPTER as machine-specific; do not copy values between systems","Print the available-adapter list in any failure path so users can self-diagnose"],"tags":["rust","wgpu","gpu","vulkan","adapter-selection","app-initialization"],"backgroundTag":"no-vulkan-device-found","analyzedSha":"c507b356453361e31638b8bff8f6d46b6da2961e","analyzedAt":"2026-08-16T21:57:18.596Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}