{"record":{"id":"fa943b65e32c6405","repo":"stride3d/stride","slug":"none-of-the-supported-surface-extensions-vk-khr-xcb-surface","errorCode":null,"errorMessage":"None of the supported surface extensions VK_KHR_xcb_surface or VK_KHR_xlib_surface is available","messagePattern":"None of the supported surface extensions VK_KHR_xcb_surface or VK_KHR_xlib_surface is available","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs","lineNumber":344,"sourceCode":"            if (!availableExtensionNames.Contains(VK_KHR_SURFACE_EXTENSION_NAME))\n                throw new InvalidOperationException($\"Required extension {Encoding.UTF8.GetString(VK_KHR_SURFACE_EXTENSION_NAME)} is not available\");\n\n            if (Platform.Type == PlatformType.Windows)\n            {\n                if (!availableExtensionNames.Contains(VK_KHR_WIN32_SURFACE_EXTENSION_NAME))\n                    throw new InvalidOperationException($\"Required extension {Encoding.UTF8.GetString(VK_KHR_WIN32_SURFACE_EXTENSION_NAME)} is not available\");\n            }\n            else if (Platform.Type == PlatformType.Android)\n            {\n                if (!availableExtensionNames.Contains(VK_KHR_ANDROID_SURFACE_EXTENSION_NAME))\n                    throw new InvalidOperationException($\"Required extension {Encoding.UTF8.GetString(VK_KHR_ANDROID_SURFACE_EXTENSION_NAME)} is not available\");\n            }\n            else if (Platform.Type == PlatformType.Linux)\n            {\n                if (!availableExtensionNames.Contains(VK_KHR_XLIB_SURFACE_EXTENSION_NAME)\n                    && !availableExtensionNames.Contains(VK_KHR_XCB_SURFACE_EXTENSION_NAME))\n                {\n                    throw new InvalidOperationException(\"None of the supported surface extensions VK_KHR_xcb_surface or VK_KHR_xlib_surface is available\");\n                }\n            }\n            else if (Platform.Type == PlatformType.macOS || Platform.Type == PlatformType.iOS)\n            {\n                if (!availableExtensionNames.Contains(VK_EXT_METAL_SURFACE_EXTENSION_NAME))\n                    throw new InvalidOperationException($\"Required extension {Encoding.UTF8.GetString(VK_EXT_METAL_SURFACE_EXTENSION_NAME)} is not available\");\n            }\n        }\n\n        private static VkUtf8String GetPlatformRelatedSurfaceExtensionName(HashSet<VkUtf8String> availableExtensionNames)\n        {\n            VkUtf8String surfaceExtensionName = VK_KHR_SURFACE_EXTENSION_NAME;\n\n            if (Platform.Type == PlatformType.Windows)\n            {\n                surfaceExtensionName = VK_KHR_WIN32_SURFACE_EXTENSION_NAME;\n            }\n            else if (Platform.Type == PlatformType.Android)","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs#L326-L362","documentation":"On Linux, Stride can use either VK_KHR_xlib_surface or VK_KHR_xcb_surface to present to X11. If the Vulkan ICD exposes neither, adapter initialization throws InvalidOperationException because no X11 presentation surface can be created.","triggerScenarios":"Enumerating adapters on Linux (X11) when the Vulkan driver advertises neither VK_KHR_xlib_surface nor VK_KHR_xcb_surface.","commonSituations":"Headless servers or SSH sessions without X11; minimal containers lacking libX11/libxcb; Wayland-only setups where the ICD omits X11 surface extensions; incomplete mesa-vulkan-drivers installs.","solutions":["Install X11 client libraries (libx11-6, libxcb1) and mesa-vulkan-drivers","Ensure DISPLAY is set and an X server is reachable","If on Wayland-only/headless, use a compositor supporting XWayland or render headless without presentation","Validate with `vulkaninfo | grep -i surface` that xcb/xlib surface extensions are listed"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var exts = VulkanExtensions.EnumerateInstanceExtensions();\nif (!exts.Contains(\"VK_KHR_xlib_surface\") && !exts.Contains(\"VK_KHR_xcb_surface\"))\n    Logger.Error(\"No X11 Vulkan surface extension available; install libx11/libxcb and mesa-vulkan-drivers.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    GraphicsAdapterFactory.Initialize();\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"VK_KHR_xcb_surface\"))\n{\n    Logger.Warn(ex, \"Linux Vulkan surface unavailable.\");\n    RunHeadlessOrFallbackBackend();\n}","preventionTips":["Include X11 libs in your container/Flatpak/AppImage dependencies","Ensure DISPLAY/XWayland is available before engine startup","Smoke-test Linux CI containers with vulkaninfo"],"tags":["vulkan","linux","x11","missing-extension"],"backgroundTag":"missing-dependency","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"}