stride3d/stride · error · InvalidOperationException

Required extension is not available

Error message

Required extension {Encoding.UTF8.GetString(VK_KHR_WIN32_SURFACE_EXTENSION_NAME)} is not available

What it means

On Windows, after VK_KHR_surface is confirmed, Stride also requires the platform extension VK_KHR_win32_surface to create a Win32 presentation surface. If the driver does not advertise it, adapter initialization throws InvalidOperationException.

Solutions

1. Install the latest vendor GPU driver (NVIDIA/AMD/Intel) for Windows
2. Reinstall the Vulkan Runtime/Loader
3. Check with `vulkaninfo` that VK_KHR_win32_surface appears in instance extensions
4. If running in a VM/remote session, enable GPU passthrough or fall back to DirectX backend

var exts = VulkanExtensions.EnumerateInstanceExtensions();
if (OperatingSystem.IsWindows() && !exts.Contains("VK_KHR_win32_surface"))
    Logger.Error("VK_KHR_win32_surface missing; reinstall vendor GPU driver.");

try
{
    GraphicsAdapterFactory.Initialize();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("VK_KHR_win32_surface"))
{
    Diagnostics.ReportDriverProblem(ex);
    UseDirectXBackend();
}

When it happens

Trigger: Enumerating graphics adapters on Windows when the Vulkan driver's vkEnumerateInstanceExtensionProperties omits VK_KHR_win32_surface.

Common situations: Generic/broken driver installs (e.g. Microsoft Basic Display Adapter without vendor driver); remote-desktop or VM environments with limited Vulkan support; corrupted ICD registry entries under HKLM\SOFTWARE\Khronos\Vulkan.

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
• None of the supported surface extensions VK_KHR_xcb_surface…
• Required extension is not available
• Could not start install package process

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

Appendix: source

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

                var name = new VkUtf8String(extensionProperty.extensionName).Span;
                var indexOfExtensionName = supportedExtensionNames.IndexOf(name);

                if (indexOfExtensionName >= 0)
                    availableExtensionNames.Add(supportedExtensionNames[indexOfExtensionName]);
            }

            return availableExtensionNames;
        }

        private static void ValidateSurfaceExtensionNamesAvailability(HashSet<VkUtf8String> availableExtensionNames)
        {
            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");

View on GitHub (pinned to 96fad776d2)