stride3d/stride · error · InvalidOperationException

Required extension is not available

Error message

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

What it means

On macOS and iOS, Stride renders Vulkan through MoltenVK and requires VK_EXT_metal_surface to create a CAMetalLayer-backed surface. If the extension is missing from the available instance extensions, initialization throws InvalidOperationException.

Solutions

1. Update/re-bundle the MoltenVK runtime with the application
2. Verify with `vulkaninfo` that VK_EXT_metal_surface is among instance extensions
3. Ensure the Vulkan loader resolves to MoltenVK (VK_ICD_FILENAMES or LoaderLayers path)
4. Refresh the Stride native binaries (vulkan libs) for the macOS/iOS target

var exts = VulkanExtensions.EnumerateInstanceExtensions();
if (!exts.Contains("VK_EXT_metal_surface"))
    Logger.Error("VK_EXT_metal_surface missing; ensure MoltenVK is bundled and loaded.");

try
{
    GraphicsAdapterFactory.Initialize();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("VK_EXT_metal_surface"))
{
    Logger.Error(ex, "MoltenVK not loaded correctly.");
    FailWithUserMessage("Metal/Vulkan runtime missing.");
}

When it happens

Trigger: Enumerating adapters on macOS/iOS when the MoltenVK ICD does not expose VK_EXT_metal_surface, at engine startup during adapter creation.

Common situations: Stale MoltenVK dylib shipped with an old build; mispackaged app missing libMoltenVK; running on a Hackintosh/unusual setup where Vulkan loader picks the wrong ICD; forgetting to bundle MoltenVK with the app.

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

• IOSurface import requires VK_EXT_metal_objects.
• AVAssetReader (audio) create failed
• AVAssetReader.StartReading (audio) failed
• Required extension is not available
• Required extension is not available

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

Appendix: source

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

                    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)
            {
                surfaceExtensionName = VK_KHR_ANDROID_SURFACE_EXTENSION_NAME;
            }
            else if (Platform.Type == PlatformType.Linux)
            {
                if (availableExtensionNames.Contains(VK_KHR_XLIB_SURFACE_EXTENSION_NAME))

View on GitHub (pinned to 96fad776d2)