stride3d/stride · error · InvalidOperationException

Required extension is not available

Error message

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

What it means

Thrown when enumerating Vulkan instance extensions, Stride discovers that the mandatory VK_KHR_surface extension is not exposed by the Vulkan loader/ICDs on the system. VK_KHR_surface is the base extension required to create any presentation surface, so without it no windowed rendering is possible. Stride throws InvalidOperationException to fail fast during GraphicsAdapter initialization.

Solutions

Install/update the vendor Vulkan driver (NVIDIA/AMD/Intel) including its surface extension support
On Linux, install mesa-vulkan-drivers / vulkanicd packages and windowing dev libraries
Verify with `vulkaninfo --summary` that VK_KHR_surface is listed among instance extensions
If rendering headless, avoid adapter paths that require surface extensions (use headless/asset-compilation mode)
Set VK_ICD_FILENAMES explicitly to a valid ICD if multiple broken ICDs are installed

Defensive patterns

Strategy: validation

Validate before calling

var exts = VulkanExtensions.EnumerateInstanceExtensions();
if (!exts.Contains("VK_KHR_surface"))
    throw new NotSupportedException("Vulkan surface extension missing; install/update GPU driver.");

Try / catch

try
{
    GraphicsAdapterFactory.Initialize();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("extension"))
{
    Logger.Warn(ex, "Vulkan surface extensions unavailable; falling back.");
    UseFallbackGraphicsBackend();
}

Prevention

Run `vulkaninfo --summary` as part of environment setup
Keep GPU drivers and Vulkan loader current
Test on headless/CI machines with SwiftShader or lavapipe if Vulkan is required

When it happens

Trigger: Calling GraphicsAdapterFactoryInstance (adapter enumeration) on a machine where the Vulkan ICD/loader does not advertise VK_KHR_surface in vkEnumerateInstanceExtensionProperties.

Common situations: Broken or missing Vulkan driver install; mesa/lavapipe lacking surface support; headless servers or CI containers without windowing libraries; stale ICD JSON files; using a software rasterizer that only exposes minimal extensions.

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

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

Appendix: source

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

            vkEnumerateInstanceExtensionProperties(extensionProperties).CheckResult();

            for (int index = 0; index < extensionCount; index++)
            {
                var extensionProperty = extensionProperties[index];
                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");
                }

View on GitHub (pinned to 96fad776d2)