{"record":{"id":"a251aa3ad89d5601","repo":"mrdoob/three.js","slug":"three-xrmanager-webgpu-xr-sessions-require-the-w","errorCode":null,"errorMessage":"THREE.XRManager: WebGPU XR sessions require the \"webgpu\" session feature. Use VRButtonGPU/XRButton with \"webgpu\" enabled or use a WebGL backend.","messagePattern":"THREE\\.XRManager: WebGPU XR sessions require the \"webgpu\" session feature\\. Use VRButtonGPU/XRButton with \"webgpu\" enabled or use a WebGL backend\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/renderers/common/XRManager.js","lineNumber":745,"sourceCode":"\n\t\treturn this._renderer.backend.isWebGPUBackend === true &&\n\t\t\tthis._session !== null &&\n\t\t\tthis._session.enabledFeatures.includes( 'webgpu' );\n\n\t}\n\n\t/**\n\t * Validates the current WebGPU XR session requirements.\n\t *\n\t * @private\n\t */\n\t_validateWebGPUSession() {\n\n\t\tif ( this._renderer.backend.isWebGPUBackend !== true ) return;\n\n\t\tif ( this._session.enabledFeatures.includes( 'webgpu' ) === false ) {\n\n\t\t\tthrow new Error( 'THREE.XRManager: WebGPU XR sessions require the \"webgpu\" session feature. Use VRButtonGPU/XRButton with \"webgpu\" enabled or use a WebGL backend.' );\n\n\t\t}\n\n\t}\n\n\t/**\n\t * Initializes the WebGPU XR projection layer and render target.\n\t *\n\t * @private\n\t * @async\n\t * @param {XRSession} session - The XR session.\n\t * @return {Promise<void>}\n\t */\n\tasync _initWebGPUSession( session ) {\n\n\t\tconst webgpuBinding = this.getWebGPUBinding();\n\t\tconst glProjLayer = webgpuBinding.createProjectionLayer( {\n\t\t\tcolorFormat: webgpuBinding.getPreferredColorFormat()","sourceCodeStart":727,"sourceCodeEnd":763,"githubUrl":"https://github.com/mrdoob/three.js/blob/da05705fa31f02710c19772a2aa70c7454807f0c/src/renderers/common/XRManager.js#L727-L763","documentation":"Thrown by XRManager._validateWebGPUSession() when the renderer uses the WebGPU backend but the XRSession was started without the 'webgpu' session feature. WebGPU XR rendering requires the session itself to be requested with `featureList: ['webgpu']` so the browser exposes a WebGPU-compatible XRDevice/projection layer.","triggerScenarios":"Calling renderer.xr.setSession(session) (or the session-start path) where the session was requested with a default/empty optionalFeatures list while the renderer is a WebGPURenderer. Using the plain VRButton/XRButton (WebGL variants) with a WebGPURenderer.","commonSituations":"Mixing WebGL-targeted XR button helpers with a WebGPU renderer. Forgetting to pass 'webgpu' into the button's optionalFeatures. Browsers/implementations that don't yet support WebGPU XR sessions. Copying a WebGL XR example and only swapping the renderer.","solutions":["Use VRButtonGPU / XRButtonGPU (or equivalent) which request the 'webgpu' session feature, when running a WebGPURenderer.","Manually request the session with 'webgpu' in optionalFeatures: `navigator.xr.requestSession('inline', { optionalFeatures: ['webgpu'] })`.","Fall back to a WebGLRenderer (WebGLBackend) if you cannot obtain a 'webgpu'-capable session.","Verify the session's enabledFeatures includes 'webgpu' before assigning it to renderer.xr."],"exampleFix":"// before (WebGL helper with WebGPU renderer)\nconst renderer = new WebGPURenderer();\ndocument.body.appendChild(VRButton.createButton(renderer)); // session lacks 'webgpu' feature\n\n// after\nimport { VRButtonGPU } from 'three/addons/webxr/VRButtonGPU.js';\nconst renderer = new WebGPURenderer();\ndocument.body.appendChild(VRButtonGPU.createButton(renderer));","handlingStrategy":"validation","validationCode":"function assertWebGPUSession(session) {\n  if (!session || !Array.isArray(session.enabledFeatures) || !session.enabledFeatures.includes('webgpu')) {\n    throw new Error('XR session missing webgpu feature; use VRButtonGPU/XRButtonGPU or request optionalFeatures:[\"webgpu\"]');\n  }\n}","typeGuard":"function isWebGPUSessionCapable(renderer, session) {\n  const isWebGPU = renderer.backend && renderer.backend.isWebGPUBackend === true;\n  return !isWebGPU || (session && session.enabledFeatures && session.enabledFeatures.includes('webgpu'));","tryCatchPattern":"try {\n  await renderer.xr.setSession(session);\n} catch (e) {\n  if (/webgpu.*session feature/i.test(e.message)) { /* fall back to WebGL renderer or re-request session with 'webgpu' */ }\n  else throw e;\n}","preventionTips":["Pair WebGPURenderer only with WebGPU-aware XR button helpers (VRButtonGPU/XRButtonGPU).","Always include 'webgpu' in optionalFeatures when requesting the XR session manually.","Detect XR backend type and refuse to start a session your backend can't satisfy."],"tags":["webgpu","webxr","vr","session-feature","config"],"backgroundTag":null,"analyzedSha":"da05705fa31f02710c19772a2aa70c7454807f0c","analyzedAt":"2026-08-12T22:51:37.160Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}