{"record":{"id":"f09281e5ee21aba4","repo":"pixijs/pixijs","slug":"rendertargetsystem-layer-must-be-0-when-renderin","errorCode":null,"errorMessage":"[RenderTargetSystem] layer must be 0 when rendering to 2D textures in WebGL.","messagePattern":"\\[RenderTargetSystem\\] layer must be 0 when rendering to 2D textures in WebGL\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/rendering/renderers/gl/renderTarget/GlRenderTargetAdaptor.ts","lineNumber":188,"sourceCode":"        this.bindFramebuffer(gpuRenderTarget.framebuffer);\n\n        if (\n            !renderTarget.isRoot\n            && renderTarget.colorAttachments.length > 0\n            && (gpuRenderTarget._attachedMipLevel !== mipLevel\n                || gpuRenderTarget._attachedLayer !== layer)\n        )\n        {\n            renderTarget.colorAttachments.forEach((attachment, i) =>\n            {\n                const colorTexture = attachment.texture;\n                const glSource = this._renderer.texture.getGlSource(colorTexture);\n\n                if (glSource.target === gl.TEXTURE_2D)\n                {\n                    if (layer !== 0)\n                    {\n                        throw new Error('[RenderTargetSystem] layer must be 0 when rendering to 2D textures in WebGL.');\n                    }\n\n                    gl.framebufferTexture2D(\n                        gl.FRAMEBUFFER,\n                        gl.COLOR_ATTACHMENT0 + i,\n                        gl.TEXTURE_2D,\n                        glSource.texture,\n                        mipLevel\n                    );\n                }\n                else if (glSource.target === (gl as any).TEXTURE_2D_ARRAY)\n                {\n                    if (this._renderer.context.webGLVersion < 2)\n                    {\n                        throw new Error('[RenderTargetSystem] Rendering to 2D array textures requires WebGL2.');\n                    }\n\n                    gl.framebufferTextureLayer(","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/pixijs/pixijs/blob/4b141e3ced7255b39c2114b6bca03421a37b2363/src/rendering/renderers/gl/renderTarget/GlRenderTargetAdaptor.ts#L170-L206","documentation":"Inside the per-attachment bind loop, when a color attachment's GL source target is TEXTURE_2D, the layer parameter must be 0 (2D textures have no slices). If a non-zero layer is requested against a 2D texture, framebufferTexture2D cannot honor it, so the adaptor throws. This catches mismatched render-target configs where a layer is set but the texture is not a 2D array / cube map.","triggerScenarios":"Binding a RenderTarget whose color texture is a plain 2D texture but passing layer !== 0; reusing a render pass that specifies a layer with a 2D-texture-backed target.","commonSituations":"Generic layer-handling code that applies a non-zero layer uniformly without checking the texture type; migrating a cube-map render path to a 2D texture but leaving the layer argument in place.","solutions":["Pass layer=0 (or omit it) when the render target's color attachment is a 2D texture.","If layered rendering is intended, back the render target with a 2D array or cube texture, not a 2D texture.","Inspect each attachment's GL source target before deciding whether to pass a non-zero layer.","Centralize layer/texture-type validation in your render-pass builder."],"exampleFix":"// before\nconst rt = new RenderTarget({ colorTextures: [tex2d] });\nrenderTargetSystem.bind(rt, undefined, 0, 1); // layer 1 on 2D\n\n// after\nconst rt = new RenderTarget({ colorTextures: [tex2d] });\nrenderTargetSystem.bind(rt, undefined, 0, 0);","handlingStrategy":"validation","validationCode":"if (layer !== 0 && glSource.target === gl.TEXTURE_2D) {\n  throw new Error('layer must be 0 for TEXTURE_2D attachments');\n}","typeGuard":"function isTexture2DTarget(target: number, gl: WebGL2RenderingContext): boolean {\n  return target === gl.TEXTURE_2D;\n}","tryCatchPattern":null,"preventionTips":["Pass layer=0 for 2D-texture-backed render targets.","Use 2D-array or cube textures when non-zero layers are needed.","Validate attachment target before applying a layer argument."],"tags":["webgl","render-target","texture","array-texture","validation"],"backgroundTag":null,"analyzedSha":"4b141e3ced7255b39c2114b6bca03421a37b2363","analyzedAt":"2026-08-12T17:27:29.507Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}