mrdoob/three.js · error · Error

THREE.WebGPUUtils: Unsupported output buffer type.

Error message

THREE.WebGPUUtils: Unsupported output buffer type.

What it means

Thrown by WebGPUUtils.getPreferredCanvasFormat when the renderer's configured outputType is a value other than undefined, UnsignedByteType, or HalfFloatType. outputType selects the GPUTextureFormat of the canvas context configuration: undefined falls back to navigator.gpu.getPreferredCanvasFormat(), UnsignedByteType maps to BGRA8Unorm, and HalfFloatType maps to RGBA16Float. These are the only canvas context formats that round-trip cleanly through a WebGPU swap chain on every device, so any other THREE texture-type constant is rejected at format selection time.

Source

Thrown at src/renderers/webgpu/utils/WebGPUUtils.js:290

			if ( this._preferredCanvasFormat === null ) {

				this._preferredCanvasFormat = navigator.gpu.getPreferredCanvasFormat();

			}

			return this._preferredCanvasFormat;

		} else if ( bufferType === UnsignedByteType ) {

			return GPUTextureFormat.BGRA8Unorm;

		} else if ( bufferType === HalfFloatType ) {

			return GPUTextureFormat.RGBA16Float;

		} else {

			throw new Error( 'THREE.WebGPUUtils: Unsupported output buffer type.' );

		}

	}

}

/**
 * Submits a single GPU command to the device queue using a shared, module-scoped
 * array to avoid per-call array allocations.
 *
 * @private
 * @param {GPUDevice} device - The GPU device.
 * @param {GPUCommandBuffer} command - The command buffer to submit.
 */
export function submit( device, command ) {

	_commandList[ 0 ] = command;

View on GitHub (pinned to da05705fa3)

Solutions

1. Omit outputType entirely to let the renderer use navigator.gpu.getPreferredCanvasFormat() (recommended default).
2. Set outputType: THREE.UnsignedByteType for 8-bit-per-channel output (lowest bandwidth, lower quality).
3. Set outputType: THREE.HalfFloatType for HDR 16-bit float output (recommended for quality).
4. Audit the config object for any constant other than the two above (especially THREE.FloatType) and remove or replace it.

Example fix

// before: 32-bit float canvas is not a valid WebGPU swap-chain format
const renderer = new THREE.WebGPURenderer({ outputType: THREE.FloatType }); // throws

// after: use a supported canvas output type, or omit it
const renderer = new THREE.WebGPURenderer({ outputType: THREE.HalfFloatType });

import { UnsignedByteType, HalfFloatType } from 'three';

const SUPPORTED_OUTPUT_TYPES = new Set( [ undefined, UnsignedByteType, HalfFloatType ] );

function resolveOutputType( outputType ) {
  if ( ! SUPPORTED_OUTPUT_TYPES.has( outputType ) ) {
    throw new Error(
      `outputType must be undefined, THREE.UnsignedByteType, or THREE.HalfFloatType (got ${ outputType })`
    );
  }
  return outputType;
}

const renderer = new THREE.WebGPURenderer( { outputType: resolveOutputType( config.outputType ) } );

import { UnsignedByteType, HalfFloatType } from 'three';

function isSupportedOutputType( value ) {
  return value === undefined || value === UnsignedByteType || value === HalfFloatType;
}

When it happens

Trigger: Constructing new THREE.WebGPURenderer({ outputType: <X> }) where X is any constant other than THREE.UnsignedByteType or THREE.HalfFloatType. Common wrong values: THREE.FloatType (full 32-bit float canvas is not a valid WebGPU context format), THREE.HalfFloatType vs the deprecated/renamed constant, a raw numeric literal, or a string. Also calling backend.utils.getPreferredCanvasFormat() after mutating backend.parameters.outputType to an unsupported value.

Common situations: Porting a WebGLRenderer configuration that used a 32-bit float output for HDR and assuming WebGPU accepts the same. Confusing outputType with outputBufferType (which defaults to HalfFloatType and has a different valid set). Passing a color-space or pixel-format constant (e.g. RGBAFormat) instead of a texture-type constant. Version changes where a previously-permissive value is now validated.

Related errors

• "transform stack empty!
• transform stack not 0
• THREE.CubeCamera.updateCoordinateSystem(): Invalid coordinat
• THREE.PassNode: Depth texture is not available for this pass
• THREE.WebGPURenderer: Shadow map type not supported yet.

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