{"record":{"id":"5c262890c521aa07","repo":"stride3d/stride","slug":"only-sdl-is-supported-for-the-time-being-on-linux","errorCode":null,"errorMessage":"Only SDL is supported for the time being on Linux","messagePattern":"Only SDL is supported for the time being on Linux","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Graphics/Vulkan/SwapChainGraphicsPresenter.Vulkan.cs","lineNumber":595,"sourceCode":"                {\n                    throw new NotSupportedException($\"Form of type [{Description.DeviceWindowHandle.GetType().Name}] is not supported. Only System.Windows.Control are supported\");\n                }\n\n                var surfaceCreateInfo = new VkWin32SurfaceCreateInfoKHR\n                {\n                    sType = VkStructureType.Win32SurfaceCreateInfoKHR,\n                    hinstance = Process.GetCurrentProcess().Handle,\n                    hwnd = controlHandle,\n                };\n                GraphicsDevice.CheckResult(GraphicsDevice.NativeInstanceApi.vkCreateWin32SurfaceKHR(GraphicsDevice.NativeInstance, &surfaceCreateInfo, null, out surface));\n            }\n            else if (Platform.Type == PlatformType.Android)\n            {\n                throw new NotImplementedException();\n            }\n            else if (Platform.Type == PlatformType.Linux)\n            {\n                throw new NotSupportedException(\"Only SDL is supported for the time being on Linux\");\n            }\n            else\n            {\n                throw new NotSupportedException();\n            }\n        }\n\n        private unsafe void CreateBackBuffers()\n        {\n            // Create the texture object\n            var backBufferDescription = new TextureDescription\n            {\n                ArraySize = 1,\n                Dimension = TextureDimension.Texture2D,\n                Height = Description.BackBufferHeight,\n                Width = Description.BackBufferWidth,\n                Depth = 1,\n                Flags = TextureFlags.RenderTarget,","sourceCodeStart":577,"sourceCodeEnd":613,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Vulkan/SwapChainGraphicsPresenter.Vulkan.cs#L577-L613","documentation":"Stride's Vulkan SwapChainGraphicsPresenter.CreateSurface supports only SDL as a windowing surface backend on Linux; when the platform type is Linux but the active window/input backend is something else (e.g. X11/Wayland/GLFW-based presenter), it throws NotSupportedException. This is an explicit limitation: the Vulkan surface creation code path is only wired up for SDL2 on Linux.","triggerScenarios":"Instantiating a Vulkan SwapChainGraphicsPresenter on Linux whose window handle is provided by anything other than an SDL window; the if/else chain in CreateSurface checks Platform.Type == PlatformType.Linux and throws because no non-SDL surface-creation branch (vkCreateXcbSurfaceKHR / vkCreateWaylandSurfaceKHR) exists.","commonSituations":"Running a Stride game under a bare X11 or Wayland desktop with the Vulkan renderer while using a native (non-SDL) game window; embedding Stride in a custom windowing toolkit; headless/CI Linux environments with no display server; distro builds that swapped SDL for another input library.","solutions":["Use the SDL2 windowing backend on Linux: create your game window via SDL2 (Stride's default SDL windowing on Linux) instead of a custom/native window handle.","Switch the graphics API from Vulkan to Direct3D-independent backends available on Linux, e.g. request the Vulkan presenter only when SDL is in use, or fall back to a different GraphicsBackend in your Game settings.","If you must use a native X11/Wayland window, add a branch in CreateSurface calling vkCreateXcbSurfaceKHR/vkCreateWaylandSurfaceKHR (patch Stride source).","Ensure the SDL2 native libraries are installed (libsdl2) so the SDL path actually initializes; a missing SDL lib can push initialization down a non-SDL path."],"exampleFix":"// before: custom non-SDL window on Linux\nvar window = new MyX11Window();\nvar presenter = new SwapChainGraphicsPresenter(device, new PresentationParameters { SourcePtr = window.Handle });\n\n// after: use SDL2 window (Stride's supported Linux path)\nusing var sdlWindow = new GameWindow(Stride.Graphics.Sdl.Sdl2Window(\"App\", 1280, 720));\nvar presenter = new SwapChainGraphicsPresenter(device, new PresentationParameters { SourcePtr = sdlWindow.NativeWindow.NativePtr });","handlingStrategy":"fallback","validationCode":"if (Platform.Type == PlatformType.Linux && !(window is SdlWindow))\n    throw new InvalidOperationException(\"On Linux, Stride's Vulkan presenter requires an SDL2 window.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    return new SwapChainGraphicsPresenter(device, parameters);\n}\ncatch (NotSupportedException ex) when (Platform.Type == PlatformType.Linux && ex.Message.Contains(\"SDL\"))\n{\n    log.Warn(\"Non-SDL Vulkan window unsupported on Linux; falling back.\");\n    return CreateFallbackPresenter(device, parameters);\n}","preventionTips":["Always build Linux game windows through Stride's SDL2 GameWindow instead of raw X11/Wayland handles.","Keep libsdl2 installed and verified at startup on Linux targets.","Document the SDL-only Linux Vulkan constraint in your deployment checklist.","Add a startup capability check that fails fast with a clear message before creating the swap chain."],"tags":["vulkan","linux","unsupported-platform","swapchain"],"backgroundTag":"unsupported-platform","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"}