{"record":{"id":"a2190d48645717a9","repo":"stride3d/stride","slug":"required-extension-encoding-utf8-getstring-vk-ext-metal","errorCode":null,"errorMessage":"Required extension {Encoding.UTF8.GetString(VK_EXT_METAL_SURFACE_EXTENSION_NAME)} is not available","messagePattern":"Required extension (.+?) is not available","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs","lineNumber":350,"sourceCode":"                    throw new InvalidOperationException($\"Required extension {Encoding.UTF8.GetString(VK_KHR_WIN32_SURFACE_EXTENSION_NAME)} is not available\");\n            }\n            else if (Platform.Type == PlatformType.Android)\n            {\n                if (!availableExtensionNames.Contains(VK_KHR_ANDROID_SURFACE_EXTENSION_NAME))\n                    throw new InvalidOperationException($\"Required extension {Encoding.UTF8.GetString(VK_KHR_ANDROID_SURFACE_EXTENSION_NAME)} is not available\");\n            }\n            else if (Platform.Type == PlatformType.Linux)\n            {\n                if (!availableExtensionNames.Contains(VK_KHR_XLIB_SURFACE_EXTENSION_NAME)\n                    && !availableExtensionNames.Contains(VK_KHR_XCB_SURFACE_EXTENSION_NAME))\n                {\n                    throw new InvalidOperationException(\"None of the supported surface extensions VK_KHR_xcb_surface or VK_KHR_xlib_surface is available\");\n                }\n            }\n            else if (Platform.Type == PlatformType.macOS || Platform.Type == PlatformType.iOS)\n            {\n                if (!availableExtensionNames.Contains(VK_EXT_METAL_SURFACE_EXTENSION_NAME))\n                    throw new InvalidOperationException($\"Required extension {Encoding.UTF8.GetString(VK_EXT_METAL_SURFACE_EXTENSION_NAME)} is not available\");\n            }\n        }\n\n        private static VkUtf8String GetPlatformRelatedSurfaceExtensionName(HashSet<VkUtf8String> availableExtensionNames)\n        {\n            VkUtf8String surfaceExtensionName = VK_KHR_SURFACE_EXTENSION_NAME;\n\n            if (Platform.Type == PlatformType.Windows)\n            {\n                surfaceExtensionName = VK_KHR_WIN32_SURFACE_EXTENSION_NAME;\n            }\n            else if (Platform.Type == PlatformType.Android)\n            {\n                surfaceExtensionName = VK_KHR_ANDROID_SURFACE_EXTENSION_NAME;\n            }\n            else if (Platform.Type == PlatformType.Linux)\n            {\n                if (availableExtensionNames.Contains(VK_KHR_XLIB_SURFACE_EXTENSION_NAME))","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs#L332-L368","documentation":"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.","triggerScenarios":"Enumerating adapters on macOS/iOS when the MoltenVK ICD does not expose VK_EXT_metal_surface, at engine startup during adapter creation.","commonSituations":"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.","solutions":["Update/re-bundle the MoltenVK runtime with the application","Verify with `vulkaninfo` that VK_EXT_metal_surface is among instance extensions","Ensure the Vulkan loader resolves to MoltenVK (VK_ICD_FILENAMES or LoaderLayers path)","Refresh the Stride native binaries (vulkan libs) for the macOS/iOS target"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var exts = VulkanExtensions.EnumerateInstanceExtensions();\nif (!exts.Contains(\"VK_EXT_metal_surface\"))\n    Logger.Error(\"VK_EXT_metal_surface missing; ensure MoltenVK is bundled and loaded.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    GraphicsAdapterFactory.Initialize();\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"VK_EXT_metal_surface\"))\n{\n    Logger.Error(ex, \"MoltenVK not loaded correctly.\");\n    FailWithUserMessage(\"Metal/Vulkan runtime missing.\");\n}","preventionTips":["Always bundle and code-sign MoltenVK dylibs with macOS/iOS builds","Update MoltenVK with each engine update","Verify extension presence in a startup diagnostic before creating the device"],"tags":["vulkan","macos","ios","moltenvk","missing-extension"],"backgroundTag":"missing-dependency","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}