{"record":{"id":"7512d31426749660","repo":"stride3d/stride","slug":"required-extension-encoding-utf8-getstring-vk-khr-surface","errorCode":null,"errorMessage":"Required extension {Encoding.UTF8.GetString(VK_KHR_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":327,"sourceCode":"            vkEnumerateInstanceExtensionProperties(extensionProperties).CheckResult();\n\n            for (int index = 0; index < extensionCount; index++)\n            {\n                var extensionProperty = extensionProperties[index];\n                var name = new VkUtf8String(extensionProperty.extensionName).Span;\n                var indexOfExtensionName = supportedExtensionNames.IndexOf(name);\n\n                if (indexOfExtensionName >= 0)\n                    availableExtensionNames.Add(supportedExtensionNames[indexOfExtensionName]);\n            }\n\n            return availableExtensionNames;\n        }\n\n        private static void ValidateSurfaceExtensionNamesAvailability(HashSet<VkUtf8String> availableExtensionNames)\n        {\n            if (!availableExtensionNames.Contains(VK_KHR_SURFACE_EXTENSION_NAME))\n                throw new InvalidOperationException($\"Required extension {Encoding.UTF8.GetString(VK_KHR_SURFACE_EXTENSION_NAME)} is not available\");\n\n            if (Platform.Type == PlatformType.Windows)\n            {\n                if (!availableExtensionNames.Contains(VK_KHR_WIN32_SURFACE_EXTENSION_NAME))\n                    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                }","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs#L309-L345","documentation":"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.","triggerScenarios":"Calling GraphicsAdapterFactoryInstance (adapter enumeration) on a machine where the Vulkan ICD/loader does not advertise VK_KHR_surface in vkEnumerateInstanceExtensionProperties.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var exts = VulkanExtensions.EnumerateInstanceExtensions();\nif (!exts.Contains(\"VK_KHR_surface\"))\n    throw new NotSupportedException(\"Vulkan surface extension missing; install/update GPU driver.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    GraphicsAdapterFactory.Initialize();\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"extension\"))\n{\n    Logger.Warn(ex, \"Vulkan surface extensions unavailable; falling back.\");\n    UseFallbackGraphicsBackend();\n}","preventionTips":["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"],"tags":["vulkan","graphics","missing-extension","initialization"],"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"}