FrameGraphClearTextureTask ${this.name}: the depth texture (

Error message

FrameGraphClearTextureTask ${this.name}: the depth texture (${depthSamples} samples) and the target texture (${textureSamples} samples) must have the same number of samples.

What it means

FrameGraphClearTextureTask.record() validates that the depth texture attachment and the target (color) texture have the same sample count. In Babylon.js FrameGraph, rendering to a texture and simultaneously clearing an MSAA depth attachment requires matching samples, otherwise the GPU render pass layout is invalid. The check treats samples of 0 or 1 as equivalent non-MSAA, and throws only when both are non-zero and differ.

Source

Thrown at packages/dev/core/src/FrameGraph/Tasks/Texture/clearTextureTask.ts:104

        }
        if (this.depthTexture !== undefined) {
            textureManager.resolveDanglingHandle(this.outputDepthTexture, this.depthTexture);
        }
        if (this.targetTexture !== undefined && this.depthTexture !== undefined) {
            const targetDescription = textureManager.getTextureDescription(targetTextures![0]);
            const depthDescription = textureManager.getTextureDescription(this.depthTexture);

            if (targetDescription.size.width !== depthDescription.size.width || targetDescription.size.height !== depthDescription.size.height) {
                throw new Error(
                    `FrameGraphClearTextureTask ${this.name}: the depth texture (size: ${depthDescription.size.width}x${depthDescription.size.height}) and the target texture (size: ${targetDescription.size.width}x${targetDescription.size.height}) must have the same dimensions.`
                );
            }

            const textureSamples = targetDescription.options.samples || 1;
            const depthSamples = depthDescription.options.samples || 1;

            if (textureSamples !== depthSamples && textureSamples !== 0 && depthSamples !== 0) {
                throw new Error(
                    `FrameGraphClearTextureTask ${this.name}: the depth texture (${depthSamples} samples) and the target texture (${textureSamples} samples) must have the same number of samples.`
                );
            }
        }

        const attachments = this._frameGraph.engine.buildTextureLayout(
            targetTextures ? Array(targetTextures.length).fill(true) : [],
            this.targetTexture === backbufferColorTextureHandle && !this._frameGraph.textureManager.backBufferTextureOverriden
        );

        const color = TmpColors.Color4[0];

        const pass = this._frameGraph.addRenderPass(this.name);

        pass.setRenderTarget(targetTextures);
        pass.setRenderTargetDepth(this.depthTexture);
        pass.setInitializeFunc(() => {
            const renderTargetWrapper = pass.frameGraphRenderTarget.renderTargetWrapper;

View on GitHub (pinned to 0592b347b8)

Solutions

Set the depth texture's options.samples to match the target texture's samples (or vice versa) when creating the texture descriptions/handles.
If you don't need depth clearing, remove the depthTexture assignment so only the color target is cleared.
If you don't need MSAA, set samples to 1 (or 0) on both textures so the check passes.

Example fix

// before
const target = fg.createTexture({ name: 'color', options: { samples: 4 } });
const depth = fg.createTexture({ name: 'depth', options: {} });
clearTask.targetTexture = target;
clearTask.depthTexture = depth;
// after
const depth = fg.createTexture({ name: 'depth', options: { samples: 4 } });

Defensive patterns

Strategy: validation

Validate before calling

const tSamples = targetDesc.options.samples || 1;
const dSamples = depthDesc.options.samples || 1;
if (tSamples !== dSamples) {
  throw new Error(`Sample mismatch: target=${tSamples}, depth=${dSamples}`);
}

Prevention

Create depth textures with the same options.samples as their paired color targets in a shared helper.
Centralize texture creation so MSAA settings come from a single config object.

When it happens

Trigger: Adding a FrameGraphClearTextureTask, setting both task.depthTexture and task.targetTexture (via task target/depth handle assignment), then calling frameGraph.build()/task.record() where one texture was created with options.samples > 1 (e.g. 4) and the other with samples 1/undefined.

Common situations: Mixing an MSAA target texture created via createTexture with samples:4 and a non-MSAA depth texture handle; wiring a depth texture from another task that has different sampling; copying pipeline configs between WebGPU (MSAA) and WebGL (non-MSAA) projects.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/45ab09be64af51e0. Report an issue: GitHub.