{"record":{"id":"0bfe15d3ab8b78d9","repo":"stride3d/stride","slug":"required-extension-encoding-utf8-getstring-vk-khr-android","errorCode":null,"errorMessage":"Required extension {Encoding.UTF8.GetString(VK_KHR_ANDROID_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":337,"sourceCode":"            }\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                }\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        {","sourceCodeStart":319,"sourceCodeEnd":355,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs#L319-L355","documentation":"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.","triggerScenarios":"Enumerating graphics adapters on an Android device whose Vulkan driver lacks VK_KHR_android_surface, during app startup when the graphics device is created.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var exts = VulkanExtensions.EnumerateInstanceExtensions();\nif (!exts.Contains(\"VK_KHR_android_surface\"))\n    Log.Warn(\"Device lacks VK_KHR_android_surface; Vulkan presentation unavailable.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    GraphicsAdapterFactory.Initialize();\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"VK_KHR_android_surface\"))\n{\n    SwitchToOpenGLESRenderer();\n}","preventionTips":["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"],"tags":["vulkan","android","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"}