mrdoob/three.js · error · Error

THREE.DepthTexture: format must be either THREE.DepthFormat

Error message

THREE.DepthTexture: format must be either THREE.DepthFormat or THREE.DepthStencilFormat

What it means

Thrown by the DepthTexture constructor when the format argument is neither THREE.DepthFormat nor THREE.DepthStencilFormat. A depth texture's GPU resource must be a depth or depth-stencil image; color formats (RGBAFormat, RedFormat, etc.) are meaningless for depth attachment, so the constructor rejects them eagerly. Note format is the 10th positional parameter with a default of DepthFormat, so a misaligned argument list is the most frequent real cause.

Source

Thrown at src/textures/DepthTexture.js:32

	 * Constructs a new depth texture.
	 *
	 * @param {number} width - The width of the texture.
	 * @param {number} height - The height of the texture.
	 * @param {number} [type=UnsignedIntType] - The texture type.
	 * @param {number} [mapping=Texture.DEFAULT_MAPPING] - The texture mapping.
	 * @param {number} [wrapS=ClampToEdgeWrapping] - The wrapS value.
	 * @param {number} [wrapT=ClampToEdgeWrapping] - The wrapT value.
	 * @param {number} [magFilter=LinearFilter] - The mag filter value.
	 * @param {number} [minFilter=LinearFilter] - The min filter value.
	 * @param {number} [anisotropy=Texture.DEFAULT_ANISOTROPY] - The anisotropy value.
	 * @param {number} [format=DepthFormat] - The texture format.
	 * @param {number} [depth=1] - The depth of the texture.
	 */
	constructor( width, height, type = UnsignedIntType, mapping, wrapS, wrapT, magFilter = NearestFilter, minFilter = NearestFilter, anisotropy, format = DepthFormat, depth = 1 ) {

		if ( format !== DepthFormat && format !== DepthStencilFormat ) {

			throw new Error( 'THREE.DepthTexture: format must be either THREE.DepthFormat or THREE.DepthStencilFormat' );

		}

		const image = { width: width, height: height, depth: depth };

		super( image, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy );

		/**
		 * This flag can be used for type testing.
		 *
		 * @type {boolean}
		 * @readonly
		 * @default true
		 */
		this.isDepthTexture = true;

		/**
		 * If set to `true`, the texture is flipped along the vertical axis when

View on GitHub (pinned to da05705fa3)

Solutions

Pass THREE.DepthFormat (depth-only) or THREE.DepthStencilFormat (depth + stencil) explicitly as the format argument.
Count positional arguments against the signature (width, height, type, mapping, wrapS, wrapT, magFilter, minFilter, anisotropy, format, depth); prefer relying on defaults and passing only the trailing format you need.
Use object-spread / default-friendly call sites (e.g. new THREE.DepthTexture(w, h, THREE.UnsignedIntType, undefined, undefined, undefined, undefined, undefined, undefined, THREE.DepthStencilFormat)) to keep the slot alignment explicit.
If a color-format depth attachment was intended, that is not supported; switch to a regular Texture for color data.

Example fix

// before: format landed in the wrong positional slot (type's slot)
const dt = new THREE.DepthTexture( 1024, 1024, THREE.RGBAFormat ); // throws

// after: depth-only with correct slots, or depth+stencil
const depthOnly = new THREE.DepthTexture( 1024, 1024, THREE.UnsignedIntType );
const depthStencil = new THREE.DepthTexture(
  1024, 1024, THREE.UnsignedInt248Type,
  undefined, undefined, undefined, undefined, undefined, undefined,
  THREE.DepthStencilFormat
);

Defensive patterns

Strategy: validation

Validate before calling

import { DepthFormat, DepthStencilFormat } from 'three';

const ALLOWED_DEPTH_FORMATS = new Set( [ DepthFormat, DepthStencilFormat ] );

function assertDepthFormat( format ) {
  if ( ! ALLOWED_DEPTH_FORMATS.has( format ) ) {
    throw new Error(
      `DepthTexture format must be THREE.DepthFormat or THREE.DepthStencilFormat (got ${ format })`
    );
  }
}

assertDepthFormat( myFormat );
const depthTexture = new THREE.DepthTexture( w, h, type, undefined, undefined, undefined, undefined, undefined, undefined, myFormat );

Type guard

import { DepthFormat, DepthStencilFormat } from 'three';

function isValidDepthFormat( format ) {
  return format === DepthFormat || format === DepthStencilFormat;
}

Prevention

Always pass format explicitly as the 10th positional argument; do not rely on positional memory for an 11-parameter constructor.
Use THREE.DepthFormat for depth-only render targets and THREE.DepthStencilFormat when stencil is required.
Never reuse a color-format constant (RGBAFormat, RedFormat, ...) for DepthTexture.
Validate the format constant once at module load to catch stale or renamed imports across three.js versions.

When it happens

Trigger: Constructing new THREE.DepthTexture(width, height, ...) with format set to a color format constant. Misaligning the 11 positional parameters (width, height, type, mapping, wrapS, wrapT, magFilter, minFilter, anisotropy, format, depth) so that a value intended for an earlier slot lands in the format slot. Passing a string or a stale constant from a different THREE version.

Common situations: Copying a Texture constructor call and assuming DepthTexture accepts the same format set. Passing format as the 3rd argument (where type belongs) because that ordering is familiar from other textures. Upgrading three.js across a version where DepthTexture became strict about format. Needing stencil and forgetting to switch from the DepthFormat default to DepthStencilFormat (or vice-versa, that case works fine, but passing RGBAFormat for stencil fails).

Related errors

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