{"record":{"id":"c4f052f6bef7088f","repo":"mrdoob/three.js","slug":"three-webgpubackend-unable-to-create-webgpu-adapt","errorCode":null,"errorMessage":"THREE.WebGPUBackend: Unable to create WebGPU adapter.","messagePattern":"THREE\\.WebGPUBackend: Unable to create WebGPU adapter\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/renderers/webgpu/WebGPUBackend.js","lineNumber":225,"sourceCode":"\t\tconst parameters = this.parameters;\n\n\t\t// create the device if it is not passed with parameters\n\n\t\tlet device;\n\n\t\tif ( parameters.device === undefined ) {\n\n\t\t\tconst adapterOptions = {\n\t\t\t\tpowerPreference: parameters.powerPreference,\n\t\t\t\tfeatureLevel: 'compatibility',\n\t\t\t\txrCompatible: renderer.xr.enabled\n\t\t\t};\n\n\t\t\tconst adapter = ( typeof navigator !== 'undefined' ) ? await navigator.gpu.requestAdapter( adapterOptions ) : null;\n\n\t\t\tif ( adapter === null ) {\n\n\t\t\t\tthrow new Error( 'THREE.WebGPUBackend: Unable to create WebGPU adapter.' );\n\n\t\t\t}\n\n\t\t\t// feature support\n\n\t\t\tconst features = Object.values( GPUFeatureName );\n\n\t\t\tconst supportedFeatures = [];\n\n\t\t\tfor ( const name of features ) {\n\n\t\t\t\tif ( adapter.features.has( name ) ) {\n\n\t\t\t\t\tsupportedFeatures.push( name );\n\n\t\t\t\t}\n\n\t\t\t}","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/mrdoob/three.js/blob/da05705fa31f02710c19772a2aa70c7454807f0c/src/renderers/webgpu/WebGPUBackend.js#L207-L243","documentation":"Thrown by WebGPUBackend.init() when navigator.gpu.requestAdapter() resolves to null (or navigator.gpu is absent and the call is skipped). A null adapter means the browser could not provide any WebGPU-capable GPU adapter under the requested options — so there is no device to create and the backend cannot function.","triggerScenarios":"Constructing WebGPURenderer/WebGPUBackend in a browser without WebGPU support, with WebGPU disabled by flags, on an outdated GPU/driver, in a headless/SSR context (no navigator.gpu), or with adapterOptions the system cannot satisfy.","commonSituations":"Running in Firefox/Safari without WebGPU enabled. Linux machines without proper GPU drivers. CI/headless browsers lacking GPU adapters. Over-constrained powerPreference or featureLevel options. End-user machines with blocked/unsupported GPUs.","solutions":["Feature-detect WebGPU before constructing the renderer: `if (!navigator.gpu) { fall back to WebGL }`.","Fall back to a WebGLRenderer (WebGLBackend) when requestAdapter returns null or throws.","Relax adapterOptions (drop powerPreference/featureLevel) and retry.","Ensure the browser is WebGPU-capable and GPU drivers are up to date; in tests use a GPU-enabled headless setup (e.g. HeadlessShell with SwiftShader)."],"exampleFix":"// before\nconst renderer = new WebGPURenderer(); // throws in init() if no adapter\nawait renderer.init();\n\n// after\nlet renderer;\nif (navigator.gpu && (await navigator.gpu.requestAdapter().catch(() => null))) {\n  renderer = new WebGPURenderer();\n  await renderer.init();\n} else {\n  renderer = new WebGLRenderer();\n}","handlingStrategy":"fallback","validationCode":"async function createRendererWithFallback(params) {\n  if (navigator.gpu) {\n    const adapter = await navigator.gpu.requestAdapter({ powerPreference: params.powerPreference }).catch(() => null);\n    if (adapter) { const r = new THREE.WebGPURenderer(params); await r.init(); return { renderer: r, backend: 'webgpu' }; }\n  }\n  return { renderer: new THREE.WebGLRenderer(params), backend: 'webgl' };\n}","typeGuard":"async function webgpuSupported() {\n  return typeof navigator !== 'undefined' && !!navigator.gpu && !!(await navigator.gpu.requestAdapter().catch(() => null));\n}","tryCatchPattern":"try {\n  renderer = new THREE.WebGPURenderer(params);\n  await renderer.init();\n} catch (e) {\n  if (/Unable to create WebGPU adapter/.test(e.message)) { renderer = new THREE.WebGLRenderer(params); }\n  else throw e;\n}","preventionTips":["Feature-detect navigator.gpu and requestAdapter() before constructing a WebGPURenderer.","Always keep a WebGLRenderer fallback path for unsupported environments.","In CI/headless, run with a GPU-capable browser build (SwiftShader/HeadlessShell)."],"tags":["webgpu","init","gpu","environment","fallback","browser-support"],"backgroundTag":null,"analyzedSha":"da05705fa31f02710c19772a2aa70c7454807f0c","analyzedAt":"2026-08-12T22:51:37.160Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}