mrdoob/three.js · error · Error

THREE.XRManager: WebGPU XR sessions require the "webgpu" ses

Error message

THREE.XRManager: WebGPU XR sessions require the "webgpu" session feature. Use VRButtonGPU/XRButton with "webgpu" enabled or use a WebGL backend.

What it means

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.

Source

Thrown at src/renderers/common/XRManager.js:745

		return this._renderer.backend.isWebGPUBackend === true &&
			this._session !== null &&
			this._session.enabledFeatures.includes( 'webgpu' );

	}

	/**
	 * Validates the current WebGPU XR session requirements.
	 *
	 * @private
	 */
	_validateWebGPUSession() {

		if ( this._renderer.backend.isWebGPUBackend !== true ) return;

		if ( this._session.enabledFeatures.includes( 'webgpu' ) === false ) {

			throw new Error( 'THREE.XRManager: WebGPU XR sessions require the "webgpu" session feature. Use VRButtonGPU/XRButton with "webgpu" enabled or use a WebGL backend.' );

		}

	}

	/**
	 * Initializes the WebGPU XR projection layer and render target.
	 *
	 * @private
	 * @async
	 * @param {XRSession} session - The XR session.
	 * @return {Promise<void>}
	 */
	async _initWebGPUSession( session ) {

		const webgpuBinding = this.getWebGPUBinding();
		const glProjLayer = webgpuBinding.createProjectionLayer( {
			colorFormat: webgpuBinding.getPreferredColorFormat()

View on GitHub (pinned to da05705fa3)

Solutions

1. Use VRButtonGPU / XRButtonGPU (or equivalent) which request the 'webgpu' session feature, when running a WebGPURenderer.
2. Manually request the session with 'webgpu' in optionalFeatures: `navigator.xr.requestSession('inline', { optionalFeatures: ['webgpu'] })`.
3. Fall back to a WebGLRenderer (WebGLBackend) if you cannot obtain a 'webgpu'-capable session.
4. Verify the session's enabledFeatures includes 'webgpu' before assigning it to renderer.xr.

Example fix

// before (WebGL helper with WebGPU renderer)
const renderer = new WebGPURenderer();
document.body.appendChild(VRButton.createButton(renderer)); // session lacks 'webgpu' feature

// after
import { VRButtonGPU } from 'three/addons/webxr/VRButtonGPU.js';
const renderer = new WebGPURenderer();
document.body.appendChild(VRButtonGPU.createButton(renderer));

function assertWebGPUSession(session) {
  if (!session || !Array.isArray(session.enabledFeatures) || !session.enabledFeatures.includes('webgpu')) {
    throw new Error('XR session missing webgpu feature; use VRButtonGPU/XRButtonGPU or request optionalFeatures:["webgpu"]');
  }
}

function isWebGPUSessionCapable(renderer, session) {
  const isWebGPU = renderer.backend && renderer.backend.isWebGPUBackend === true;
  return !isWebGPU || (session && session.enabledFeatures && session.enabledFeatures.includes('webgpu'));

try {
  await renderer.xr.setSession(session);
} catch (e) {
  if (/webgpu.*session feature/i.test(e.message)) { /* fall back to WebGL renderer or re-request session with 'webgpu' */ }
  else throw e;
}

When it happens

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

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

Related errors

• THREE.CubeCamera.updateCoordinateSystem(): Invalid coordinat
• THREE.Renderer: .compileComputeAsync() expects a ComputeNode
• THREE.Renderer: .render() called before the backend is initi
• THREE.Renderer: "getArrayBufferAsync()" offset and count mus
• THREE.Renderer: .compute() expects a ComputeNode.

AI-assisted analysis of mrdoob/three.js@da05705fa3 (2026-08-12). Data as JSON: /api/errors/a251aa3ad89d5601. Report an issue: GitHub.