stride3d/stride · error · InvalidOperationException

Required extension is not available

Error message

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

What it means

On Android, Stride requires VK_KHR_android_surface so the engine can create an ANativeWindow-backed Vulkan surface. If the device/driver does not expose it, adapter initialization throws InvalidOperationException.

Solutions

Test on a device/emulator image with full Vulkan support (API 24+ with a real GPU driver)
Update device drivers via system update or switch to a supported test device
Check `vulkaninfo`/`adb shell dumpsys` that VK_KHR_android_surface is available
Fall back to OpenGL ES backend for unsupported devices

Defensive patterns

Strategy: validation

Validate before calling

var exts = VulkanExtensions.EnumerateInstanceExtensions();
if (!exts.Contains("VK_KHR_android_surface"))
    Log.Warn("Device lacks VK_KHR_android_surface; Vulkan presentation unavailable.");

Try / catch

try
{
    GraphicsAdapterFactory.Initialize();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("VK_KHR_android_surface"))
{
    SwitchToOpenGLESRenderer();
}

Prevention

Set minimum device requirements (Android 7+, Vulkan-capable GPU) in the store listing
Test on the oldest supported device and on emulators with real GPU images
Detect Vulkan capability at runtime and fall back to GLES

When it happens

Trigger: Enumerating graphics adapters on an Android device whose Vulkan driver lacks VK_KHR_android_surface, during app startup when the graphics device is created.

Common situations: Very old devices or emulators without real Vulkan support; emulators with SwiftShader/obsolete images; vendor drivers stripped of the surface extension; running on a device below Android 7.0 with partial 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

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

Appendix: source

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

            }

            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");
            }
        }

        private static VkUtf8String GetPlatformRelatedSurfaceExtensionName(HashSet<VkUtf8String> availableExtensionNames)
        {

View on GitHub (pinned to 96fad776d2)