GraphiteEditor/Graphite · critical

Failed to create WGPU context

Error message

Failed to create WGPU context

What it means

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.

Source

Thrown at desktop/src/gpu_context.rs:15

use crate::wrapper::{WgpuContext, WgpuContextBuilder, WgpuFeatures};

pub(super) async fn create_wgpu_context() -> WgpuContext {
	let mut wgpu_context_builder = WgpuContextBuilder::new().with_features(WgpuFeatures::IMMEDIATES);

	// TODO: make this configurable via cli flags instead
	if let Some(index) = std::env::var("GRAPHITE_WGPU_ADAPTER").ok().and_then(|s| s.parse().ok()) {
		tracing::info!("Overriding WGPU adapter selection with adapter index {index}");
		wgpu_context_builder = wgpu_context_builder.with_selection(index);
	}

	// TODO: add a cli flag to list adapters and exit instead of always printing
	println!("\nAvailable WGPU adapters:\n{}", wgpu_context_builder.available_adapters_fmt().await);

	let wgpu_context = wgpu_context_builder.build().await.expect("Failed to create WGPU context");

	// TODO: add a cli flag to list adapters and exit instead of always printing
	println!("Using WGPU adapter: {:?}", wgpu_context.adapter.get_info());

	wgpu_context
}

View on GitHub (pinned to c507b35645)

Solutions

1. Read the 'Available WGPU adapters:' list the app prints just before the panic to confirm what wgpu can see
2. On Linux install Vulkan drivers (mesa-vulkan-drivers / vulkan-radeon / proprietary NVIDIA ICD) and verify with vulkaninfo
3. Unset GRAPHITE_WGPU_ADAPTER or set it to a valid index from the printed list
4. In VMs enable 3D acceleration, or update the GPU driver on the host/Windows machine

Example fix

# before (shell)
GRAPHITE_WGPU_ADAPTER=9 ./graphite  # panics: Failed to create WGPU context

# after
unset GRAPHITE_WGPU_ADAPTER
vulkaninfo --summary  # verify an ICD is present
./graphite

// Enumerate adapters first and confirm a candidate exists before building the context
let adapters = wgpu_context_builder.available_adapters_fmt().await;
if adapters.trim().is_empty() {
	eprintln!("no WGPU adapters found; install Vulkan/GL drivers before launching");
	std::process::exit(1);
}

let Some(wgpu_context) = wgpu_context_builder.build().await else {
	eprintln!("Failed to create WGPU context. Available adapters:\n{}", wgpu_context_builder.available_adapters_fmt().await);
	eprintln!("Install Vulkan drivers or unset GRAPHITE_WGPU_ADAPTER and retry.");
	std::process::exit(1);
};

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Buffer mapping communication failed
• Failed to download texture data
• Error setting Ctrl-C handler
• Failed to initialize on-disk resource storage
• Failed to get data directory

AI-assisted analysis of GraphiteEditor/Graphite@c507b35645 (2026-08-16). Data as JSON: /api/errors/93381dedd73e86ef. Report an issue: GitHub.