{"record":{"id":"b1f9f0c16cf0297f","repo":"pixijs/pixijs","slug":"rendertarget-cannot-attach-a-depth-stencil-textu","errorCode":null,"errorMessage":"[RenderTarget] cannot attach a depth-stencil texture to the screen — the canvas owns its own depth/stencil buffers. Render to a texture target instead.","messagePattern":"\\[RenderTarget\\] cannot attach a depth-stencil texture to the screen — the canvas owns its own depth/stencil buffers\\. Render to a texture target instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/rendering/renderers/shared/renderTarget/RenderTarget.ts","lineNumber":277,"sourceCode":"                colorAttachments.push({\n                    texture: texture.source,\n                    loadOp: 'clear',\n                    storeOp: 'store',\n                });\n            });\n        }\n\n        const wantsDepthStencilTexture = opts.depthStencilTexture === true;\n\n        this._depth = !!(opts.depth || wantsDepthStencilTexture);\n        this._stencil = !!(opts.stencil || wantsDepthStencilTexture);\n\n        if (opts.depthStencilTexture instanceof Texture\n            || opts.depthStencilTexture instanceof TextureSource)\n        {\n            if (opts.isRoot)\n            {\n                throw new Error('[RenderTarget] cannot attach a depth-stencil texture to the screen — '\n                    + 'the canvas owns its own depth/stencil buffers. Render to a texture target instead.');\n            }\n\n            depthStencilAttachment = {\n                texture: opts.depthStencilTexture.source,\n            };\n        }\n        else if ((wantsDepthStencilTexture && !opts.isRoot)\n            || ((opts.stencil || opts.depth) && colorAttachments.length === 0))\n        {\n            // an explicit texture request (depthStencilTexture: true) or a depth-only target.\n            // Plain depth/stencil flags create no texture — each backend picks the cheapest\n            // resource (renderbuffer on WebGL, internal texture on WebGPU, context buffers\n            // for the screen)\n            depthStencilAttachment = this._createDepthStencilTexture(opts.width, opts.height, opts.resolution);\n        }\n\n        return {","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/pixijs/pixijs/blob/4b141e3ced7255b39c2114b6bca03421a37b2363/src/rendering/renderers/shared/renderTarget/RenderTarget.ts#L259-L295","documentation":"Thrown by RenderTarget when a depth-stencil texture is attached to a root (screen) target. The screen/canvas owns its own depth and stencil buffers provided by the context (WebGL default framebuffer or the WebGPU canvas configuration), so an external depth-stencil texture cannot be bound there.","triggerScenarios":"Constructing a RenderTarget with `isRoot: true` together with `depthStencilTexture: <Texture|TextureSource>` (or passing such a Texture through the root render-surface options).","commonSituations":"Reusing a depth-stencil texture across both screen and offscreen passes; copying an offscreen RenderTarget config verbatim into the root target; misconfiguring the application's main render surface.","solutions":["Drop `depthStencilTexture` from the root target — let the canvas manage its own depth/stencil via `depth`/`stencil` flags or renderer configuration.","Render into an offscreen texture target (isRoot: false) if you must share a specific depth-stencil texture.","Separate your 'screen pass' configuration object from your 'offscreen pass' configuration so root-specific options never leak."],"exampleFix":"// before\nnew RenderTarget({ isRoot: true, depthStencilTexture: sharedDepthTex });\n// after\nnew RenderTarget({ isRoot: true, depth: true, stencil: true });","handlingStrategy":"validation","validationCode":"function assertRootOpts(opts) {\n  if (opts.isRoot && (opts.depthStencilTexture instanceof Texture || opts.depthStencilTexture instanceof TextureSource)) {\n    throw new Error('Root cannot take depthStencilTexture');\n  }\n}","typeGuard":"function isRootSafeOpts(opts): boolean {\n  return !opts.isRoot || !(opts.depthStencilTexture instanceof Texture || opts.depthStencilTexture instanceof TextureSource);\n}","tryCatchPattern":null,"preventionTips":["Keep root-target configs separate from offscreen configs.","Never pass a shared depth-stencil texture to an isRoot target."],"tags":["render-target","depth-stencil","canvas","root","configuration"],"backgroundTag":null,"analyzedSha":"4b141e3ced7255b39c2114b6bca03421a37b2363","analyzedAt":"2026-08-12T17:27:29.507Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}