pixijs/pixijs · error · Error

[GpuRenderTargetAdaptor] cannot get gpu color texture from a

Error message

[GpuRenderTargetAdaptor] cannot get gpu color texture from a depth-only render target

What it means

Thrown by GpuRenderTargetAdaptor._getGpuColorTexture() when asked for the GPU color texture of a render target that has zero color attachments (a depth-only target). There is no color texture to return, so the filter/blending copy that called this helper cannot proceed. The check is renderTarget.colorAttachments.length === 0.

Source

Thrown at src/rendering/renderers/gpu/renderTarget/GpuRenderTargetAdaptor.ts:231

    {
        this._renderer.encoder.endRenderPass();

        // The pass is now closed; a subsequent bind to the same target must genuinely reopen it
        // (e.g. the copyToTexture / copyColor case, which reads the resolved contents).
        this._activePass = null;
    }

    /**
     * returns the gpu texture for the first color texture in the render target
     * mainly used by the filter manager to get copy the texture for blending
     * @param renderTarget
     * @returns a gpu texture
     */
    private _getGpuColorTexture(renderTarget: RenderTarget): GPUTexture
    {
        if (renderTarget.colorAttachments.length === 0)
        {
            throw new Error('[GpuRenderTargetAdaptor] cannot get gpu color texture from a depth-only render target');
        }

        const colorTexture = renderTarget.colorAttachments[0].texture;

        if (colorTexture instanceof CanvasSource && colorTexture._gpuContext)
        {
            return colorTexture._gpuContext.getCurrentTexture();
        }

        return this._renderer.texture.getGpuSource(colorTexture);
    }

    public getDescriptor(
        renderTarget: RenderTarget,
        clear: CLEAR_OR_BOOL,
        clearValue: RgbaArray,
        mipLevel = 0,
        layer = 0

View on GitHub (pinned to 4b141e3ced)

Solutions

Ensure any render target passed to filter/copy operations has at least one color attachment.
Avoid applying color-space filters to depth-only targets.
If you only need depth, use a depth-specific copy/read path rather than the color-texture helper.

Example fix

// before
const depthOnly = new RenderTarget({ colorAttachments: [], depth: true, width: 1024, height: 1024 });
filterManager.applyFilter(depthOnly, someFilter); // internally calls _getGpuColorTexture -> throws

// after
const withColor = new RenderTarget({ colorAttachments: [colorTex], depth: true, width: 1024, height: 1024 });
filterManager.applyFilter(withColor, someFilter);

Defensive patterns

Strategy: validation

Validate before calling

function assertHasColorAttachment(rt: RenderTarget): void {
  if (rt.colorAttachments.length === 0) {
    throw new Error('Render target has no color attachment; cannot read color texture for filtering/blending.');
  }
}
assertHasColorAttachment(rt);

Type guard

function hasColorAttachment(rt: RenderTarget): boolean {
  return rt.colorAttachments.length > 0;
}

Prevention

Never route depth-only targets through filter/copy paths that read color.
Always include a color attachment on targets used with the filter manager.
Use a depth-specific copy path when only depth data is needed.

When it happens

Trigger: The filter manager (or any caller of _getGpuColorTexture) operating on a depth-only render target — e.g. applying a filter that needs to copy the color buffer for blending onto a target that has only a depth/stencil attachment.

Common situations: Applying a filter to a depth-only render target. Shadow-map targets accidentally routed through a filter/copy path. Misconfigured render target with colorAttachments omitted but depth/stencil present, used where a color texture is expected.

Related errors

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