{"record":{"id":"bda871f0a8f54cf5","repo":"stride3d/stride","slug":"cannot-clear-a-stencil-buffer-without-a-stencil-buffer","errorCode":null,"errorMessage":"Cannot clear a stencil buffer without a Stencil Buffer format [{0}].","messagePattern":"Cannot clear a stencil buffer without a Stencil Buffer format \\[(.+?)\\]\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Graphics/Direct3D11/CommandList.Direct3D11.cs","lineNumber":916,"sourceCode":"        /// <param name=\"options\">\n        ///   A combination of <see cref=\"DepthStencilClearOptions\"/> flags identifying what parts of the Depth-Stencil Buffer to clear.\n        /// </param>\n        /// <param name=\"depth\">The depth value to use for clearing the Depth Buffer.</param>\n        /// <param name=\"stencil\">The stencil value to use for clearing the Stencil Buffer.</param>\n        /// <exception cref=\"ArgumentNullException\"><paramref name=\"depthStencilBuffer\"/> is <see langword=\"null\"/>.</exception>\n        /// <exception cref=\"InvalidOperationException\">Cannot clear a Stencil Buffer without a Stencil Buffer format.</exception>\n        public void Clear(Texture depthStencilBuffer, DepthStencilClearOptions options, float depth = 1, byte stencil = 0)\n        {\n            ArgumentNullException.ThrowIfNull(depthStencilBuffer);\n            RecordDebugCounter(DebugCounterKind.Clear);\n\n            var flags = options.HasFlag(DepthStencilClearOptions.DepthBuffer) ? ClearFlag.Depth : 0;\n\n            // Check that the Depth-Stencil Buffer has a Stencil if Clear Stencil is requested\n            if (options.HasFlag(DepthStencilClearOptions.Stencil))\n            {\n                if (!depthStencilBuffer.HasStencil)\n                    throw new InvalidOperationException(string.Format(FrameworkResources.NoStencilBufferForDepthFormat, depthStencilBuffer.ViewFormat));\n\n                flags |= ClearFlag.Stencil;\n            }\n\n            nativeDeviceContext->ClearDepthStencilView(depthStencilBuffer.NativeDepthStencilView, (uint) flags, depth, stencil);\n        }\n\n        /// <summary>\n        ///   Clears the specified Render Target.\n        /// </summary>\n        /// <param name=\"renderTarget\">The Render Target to clear.</param>\n        /// <param name=\"color\">The color to use to clear the Render Target.</param>\n        /// <exception cref=\"ArgumentNullException\"><paramref name=\"renderTarget\"/> is <see langword=\"null\"/>.</exception>\n        public void Clear(Texture renderTarget, Color4 color)\n        {\n            ArgumentNullException.ThrowIfNull(renderTarget);\n            RecordDebugCounter(DebugCounterKind.Clear);\n","sourceCodeStart":898,"sourceCodeEnd":934,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Direct3D11/CommandList.Direct3D11.cs#L898-L934","documentation":"Thrown by CommandList.Clear when ClearDepthStencilClearOptions.Stencil is requested but the depth-stencil buffer's format has no stencil component (e.g. D32Float, D16). An InvalidOperationException carries the offending ViewFormat so the developer can see why. D3D11 cannot clear stencil on a stencil-less view.","triggerScenarios":"Calling commandList.Clear(depthStencilBuffer, DepthStencilClearOptions.DepthBuffer | DepthStencilClearOptions.Stencil, ...) where the buffer's format is a depth-only format without stencil (D16, D32, D32Float).","commonSituations":"Reusing a shared clear helper across depth-stencil textures created with different formats; a format switch from D24S8 to D32Float that kept stencil-clear flags; clearing render targets and depth buffers in one generic pass.","solutions":["Remove DepthStencilClearOptions.Stencil from the options when the buffer format has no stencil.","Recreate the depth-stencil buffer with a format that includes stencil (e.g. PixelFormat.D24_UNORM_S8_UInt or D32FloatS8X24).","Check depthStencilBuffer.HasStencil at the call site and clear stencil conditionally."],"exampleFix":"// before\ncommandList.Clear(depthBuffer, DepthStencilClearOptions.DepthBuffer | DepthStencilClearOptions.Stencil);\n// after\nvar options = DepthStencilClearOptions.DepthBuffer;\nif (depthBuffer.HasStencil) options |= DepthStencilClearOptions.Stencil;\ncommandList.Clear(depthBuffer, options);","handlingStrategy":"validation","validationCode":"var options = DepthStencilClearOptions.DepthBuffer;\nif (wantStencil && depthStencilBuffer.HasStencil)\n    options |= DepthStencilClearOptions.Stencil;\ncommandList.Clear(depthStencilBuffer, options);","typeGuard":"static bool CanClearStencil(Texture ds) => ds is not null && ds.HasStencil;","tryCatchPattern":"try { commandList.Clear(ds, opts); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Stencil\")) { commandList.Clear(ds, DepthStencilClearOptions.DepthBuffer); }","preventionTips":["Check depthStencilBuffer.HasStencil before requesting a stencil clear.","Standardize on stencil formats (D24_UNORM_S8_UInt) when stencil clears are part of the frame.","Clear depth and stencil with separate calls when formats may vary."],"tags":["direct3d11","graphics","depth-stencil","clear","invalid-format"],"backgroundTag":"invalid-argument-value","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}