pixijs/pixijs · error · Error

[RenderTargetSystem] Clearing array layers is not supported

Error message

[RenderTargetSystem] Clearing array layers is not supported in WebGL renderer.

What it means

Thrown by GlRenderTargetAdaptor.clear() when the layer argument is non-zero. WebGL's gl.clear clears the currently-bound framebuffer in its entirety — there is no way to clear a single array layer or cube face without first re-binding that specific layer as an attachment. So the GL adaptor refuses a per-layer clear rather than silently clearing the wrong surface.

Source

Thrown at src/rendering/renderers/gl/renderTarget/GlRenderTargetAdaptor.ts:404

        });

        gpuRenderTarget.msaaRenderBuffer = null;
    }

    public clear(
        renderTarget: RenderTarget,
        clear: CLEAR_OR_BOOL,
        clearColor?: RgbaArray,
        _viewport?: Rectangle,
        _mipLevel = 0,
        layer = 0
    )
    {
        if (!clear) return;

        if (layer !== 0)
        {
            throw new Error('[RenderTargetSystem] Clearing array layers is not supported in WebGL renderer.');
        }

        const renderTargetSystem = this._renderTargetSystem;

        // if clear is boolean..
        if (typeof clear === 'boolean')
        {
            clear = clear ? CLEAR.ALL : CLEAR.NONE;
        }

        // Strip the COLOR bit for depth-only targets – there is no color buffer to clear.
        if (renderTarget.colorAttachments.length === 0)
        {
            clear &= ~CLEAR.COLOR;

            if (!clear) return;
        }

View on GitHub (pinned to 4b141e3ced)

Solutions

Bind the specific layer first (bind with layer != 0 forces re-attachment to that face/layer), then call clear with layer 0.
Branch on backend: only pass non-zero layers to clear() when running on WebGPU.
Restructure so per-layer clears become a full bind+clear cycle on the layer of interest.

Example fix

// before
rtSystem.clear(arrayRt, CLEAR.ALL, color, viewport, 0, 3); // layer 3 on WebGL

// after
rtSystem.bind(arrayRt, CLEAR.ALL, color, viewport, 0, 3); // re-attach layer 3, clear during bind
// subsequent clears on this layer use layer 0:
rtSystem.clear(arrayRt, CLEAR.ALL, color, viewport, 0, 0);

Defensive patterns

Strategy: validation

Validate before calling

// Branch on backend: only pass layer to clear() on WebGPU
const isWebGPU = app.renderer.type === 'webgpu';
rtSystem.clear(rt, CLEAR.ALL, color, viewport, mipLevel, isWebGPU ? layer : 0);

Try / catch

try {
  rtSystem.clear(rt, CLEAR.ALL, color, viewport, mipLevel, layer);
} catch (e) {
  if (/Clearing array layers/.test((e as Error).message)) {
    // bind the layer first, then clear with layer 0
    rtSystem.bind(rt, CLEAR.ALL, color, viewport, mipLevel, layer);
  } else throw e;
}

Prevention

Treat clear() as a whole-framebuffer op on WebGL; never pass layer != 0.
Use bind() with a clear flag to clear a specific layer on WebGL.
Keep backend-specific clear logic centralized.

When it happens

Trigger: Calling clear(renderTarget, clear, clearColor, viewport, mipLevel, layer) with layer !== 0 on the WebGL renderer. Happens when shared code paths (that also serve WebGPU, where layer clears are expressible) pass a layer into the clear API.

Common situations: Engine code that clears a specific array layer uniformly across backends. Clearing a cube-map face through the clear path instead of the bind path. Porting a WebGPU-only feature to WebGL.

Related errors

AI-assisted analysis of pixijs/pixijs@4b141e3ced (2026-08-12). Data as JSON: /api/errors/d1f8e5752f3bfc7e. Report an issue: GitHub.