stride3d/stride · error · InvalidOperationException

None of the supported surface extensions VK_KHR_xcb_surface…

Error message

None of the supported surface extensions VK_KHR_xcb_surface or VK_KHR_xlib_surface is available

What it means

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.

Solutions

1. Install X11 client libraries (libx11-6, libxcb1) and mesa-vulkan-drivers
2. Ensure DISPLAY is set and an X server is reachable
3. If on Wayland-only/headless, use a compositor supporting XWayland or render headless without presentation
4. Validate with `vulkaninfo | grep -i surface` that xcb/xlib surface extensions are listed

var exts = VulkanExtensions.EnumerateInstanceExtensions();
if (!exts.Contains("VK_KHR_xlib_surface") && !exts.Contains("VK_KHR_xcb_surface"))
    Logger.Error("No X11 Vulkan surface extension available; install libx11/libxcb and mesa-vulkan-drivers.");

try
{
    GraphicsAdapterFactory.Initialize();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("VK_KHR_xcb_surface"))
{
    Logger.Warn(ex, "Linux Vulkan surface unavailable.");
    RunHeadlessOrFallbackBackend();
}

When it happens

Trigger: Enumerating adapters on Linux (X11) when the Vulkan driver advertises neither VK_KHR_xlib_surface nor VK_KHR_xcb_surface.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Required extension is not available
• Required extension is not available
• Required extension is not available
• Required extension is not available
• Only SDL is supported for the time being on Linux

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/fa943b65e32c6405. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs:344

            if (!availableExtensionNames.Contains(VK_KHR_SURFACE_EXTENSION_NAME))
                throw new InvalidOperationException($"Required extension {Encoding.UTF8.GetString(VK_KHR_SURFACE_EXTENSION_NAME)} is not available");

            if (Platform.Type == PlatformType.Windows)
            {
                if (!availableExtensionNames.Contains(VK_KHR_WIN32_SURFACE_EXTENSION_NAME))
                    throw new InvalidOperationException($"Required extension {Encoding.UTF8.GetString(VK_KHR_WIN32_SURFACE_EXTENSION_NAME)} is not available");
            }
            else if (Platform.Type == PlatformType.Android)
            {
                if (!availableExtensionNames.Contains(VK_KHR_ANDROID_SURFACE_EXTENSION_NAME))
                    throw new InvalidOperationException($"Required extension {Encoding.UTF8.GetString(VK_KHR_ANDROID_SURFACE_EXTENSION_NAME)} is not available");
            }
            else if (Platform.Type == PlatformType.Linux)
            {
                if (!availableExtensionNames.Contains(VK_KHR_XLIB_SURFACE_EXTENSION_NAME)
                    && !availableExtensionNames.Contains(VK_KHR_XCB_SURFACE_EXTENSION_NAME))
                {
                    throw new InvalidOperationException("None of the supported surface extensions VK_KHR_xcb_surface or VK_KHR_xlib_surface is available");
                }
            }
            else if (Platform.Type == PlatformType.macOS || Platform.Type == PlatformType.iOS)
            {
                if (!availableExtensionNames.Contains(VK_EXT_METAL_SURFACE_EXTENSION_NAME))
                    throw new InvalidOperationException($"Required extension {Encoding.UTF8.GetString(VK_EXT_METAL_SURFACE_EXTENSION_NAME)} is not available");
            }
        }

        private static VkUtf8String GetPlatformRelatedSurfaceExtensionName(HashSet<VkUtf8String> availableExtensionNames)
        {
            VkUtf8String surfaceExtensionName = VK_KHR_SURFACE_EXTENSION_NAME;

            if (Platform.Type == PlatformType.Windows)
            {
                surfaceExtensionName = VK_KHR_WIN32_SURFACE_EXTENSION_NAME;
            }
            else if (Platform.Type == PlatformType.Android)

View on GitHub (pinned to 96fad776d2)