{"record":{"id":"02d2ff45f88126e7","repo":"stride3d/stride","slug":"the-nameof-windowhandle-nameof-windowhandle-handle-must-not","errorCode":null,"errorMessage":"The {nameof(WindowHandle)}.{nameof(WindowHandle.Handle)} must not be zero.","messagePattern":"The (.+?)\\.(.+?) must not be zero\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Graphics/Direct3D/SwapChainGraphicsPresenter.Direct3D.cs","lineNumber":692,"sourceCode":"                    throw new NotSupportedException($\"Window context [{Description.DeviceWindowHandle.Context}] not supported while creating SwapChain\");\n            }\n\n            this.swapChain = swapChain;\n            swapChainVersion = GetLatestDxgiSwapChainVersion(swapChain);\n        }\n#else\n        /// <summary>\n        ///   Creates or reinitializes the Swap-Chain on the desktop Windows platform.\n        /// </summary>\n        /// <exception cref=\"InvalidOperationException\">\n        ///   <see cref=\"PresentationParameters.DeviceWindowHandle\"/> is <see langword=\"null\"/> or\n        ///   the <see cref=\"WindowHandle.Handle\"/> is invalid or zero.\n        /// </exception>\n        private void CreateSwapChainForWindows()\n        {\n            var hwndPtr = Description.DeviceWindowHandle.Handle;\n            if (hwndPtr == 0)\n                throw new InvalidOperationException($\"The {nameof(WindowHandle)}.{nameof(WindowHandle.Handle)} must not be zero.\");\n\n            CreateSwapChainForDesktop(hwndPtr);\n        }\n\n        private void CreateSwapChainForDesktop(IntPtr handle)\n        {\n#if STRIDE_GRAPHICS_API_DIRECT3D12\n            useFlipModel = true;\n#else\n            // https://devblogs.microsoft.com/directx/dxgi-flip-model/#what-do-i-have-to-do-to-use-flip-model\n            useFlipModel = Description.MultisampleCount == MultisampleCount.None && flipModelSupport;\n#endif\n\n            var swapchainFormat = Description.BackBufferFormat;\n            bufferCount = 1;\n\n            if (useFlipModel)\n            {","sourceCodeStart":674,"sourceCodeEnd":710,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Direct3D/SwapChainGraphicsPresenter.Direct3D.cs#L674-L710","documentation":"CreateSwapChainForWindows creates a desktop (HWND-based) DXGI swapchain, which requires a real native window handle. If WindowHandle.Handle is IntPtr.Zero there is no window to attach the swapchain to, so Stride throws InvalidOperationException before calling CreateSwapChainForDesktop.","triggerScenarios":"Constructing a SwapChainGraphicsPresenter on a non-UWP Direct3D platform while Description.DeviceWindowHandle.Handle == 0, or DeviceWindowHandle being effectively empty despite being non-null.","commonSituations":"Headless/offscreen rendering attempts on Windows (developers assume a swapchain works without a window); forgetting to pass the actual window handle from the UI framework (WinForms Control.Handle, SDL/WPF HWND) into the presenter description; ordering issues where presenter creation runs before the window is created.","solutions":["Provide a valid non-zero HWND in DeviceWindowHandle.Handle before creating the presenter.","If you only need offscreen rendering, render to a RenderTarget/Texture instead of creating a swapchain.","Ensure presenter creation happens after the native window exists and its handle is cached."],"exampleFix":"// before\nvar description = new GraphicsPresenterDescription { DeviceWindowHandle = new WindowHandle() };\n// after\nvar description = new GraphicsPresenterDescription { DeviceWindowHandle = new WindowHandle { Handle = form.Handle } };","handlingStrategy":"validation","validationCode":"if (description.DeviceWindowHandle == null || description.DeviceWindowHandle.Handle == IntPtr.Zero)\n    throw new InvalidOperationException(\"A valid window handle is required to create a swapchain\");","typeGuard":"bool HasValidHandle(WindowHandle h) => h is { Handle: not 0 };","tryCatchPattern":"try { presenter = new SwapChainGraphicsPresenter(device, desc); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"must not be zero\"))\n{ throw new ApplicationException(\"Initialize the window before creating the presenter\", ex); }","preventionTips":["Create the native window before initializing the graphics presenter","Offscreen rendering should use RenderTargets, not a swapchain","Assert Handle != IntPtr.Zero in presenter-factory code"],"tags":["direct3d","swapchain","window-handle","graphics","stride"],"backgroundTag":"empty-required-field","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"}