stride3d/stride · critical · Exception

Vulkan: Failed to find GPUs with Vulkan support

Error message

Vulkan: Failed to find GPUs with Vulkan support

What it means

During adapter initialization Stride creates a Vulkan instance and enumerates physical devices via vkEnumeratePhysicalDevices. If the count is zero, no Vulkan-capable GPU/driver is present, so initialization throws a generic Exception.

Solutions

1. Install a Vulkan-capable GPU driver (e.g. mesa-vulkan-drivers / vulkan-intel / nvidia driver with Vulkan on Linux)
2. Run vulkaninfo to verify the loader detects a GPU before launching the app
3. On headless/CI, use a CPU fallback renderer or enable a software Vulkan implementation (e.g. lavapipe/SwiftShader)
4. Update GPU drivers and the Vulkan runtime (vulkan-headers/loader) to current versions

bool vulkanAvailable = GraphicsAdapterFactory.Adapters != null && GraphicsAdapterFactory.Adapters.Count > 0;

try { GraphicsAdapterFactory.Initialize(); } catch (Exception ex) when (ex.Message.Contains("Failed to find GPUs")) { /* fall back to another renderer or show setup instructions */ }

When it happens

Trigger: Calling GraphicsAdapterFactory.Initialize (or creating any GraphicsDevice) on a machine where the Vulkan ICD/driver reports zero physical devices — no Vulkan driver installed, headless server, VM without GPU passthrough, or a broken loader.

Common situations: Linux servers without mesa-vulkan/nvidia-vulkan drivers; Windows machines with outdated GPU drivers; CI containers without GPU; remote desktop sessions masking the GPU.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Failed to initialize the audio native layer.
• Failed to create vulkan instance
• Required extension is not available
• Vulkan: Dynamic rendering and synchronization2 are not…
• Required Vulkan extension

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

Appendix: source

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

            // If no loader is available, fall back to the bundled MoltenVK at runtimes/<rid>/native/.
            // On iOS, MoltenVK is statically linked into the app binary: dlopen the executable itself,
            // which exports vkGetInstanceProcAddr (see Stride.Core.NativeLibraries.targets).
            string vkLibraryName = Platform.Type switch
            {
                PlatformType.macOS => ResolveMacOSVulkanLibrary(),
                PlatformType.iOS => Environment.ProcessPath,
                _ => null,
            };
            var result = vkInitialize(vkLibraryName);
            result.CheckResult();

            // Create the default instance to enumerate physical devices
            defaultInstance = new GraphicsAdapterFactoryInstance(false);
            uint physicalDevicesCount = 0;
            defaultInstance.NativeInstanceApi.vkEnumeratePhysicalDevices(defaultInstance.NativeInstance, &physicalDevicesCount, null).CheckResult();

            if (physicalDevicesCount == 0)
                throw new Exception("Vulkan: Failed to find GPUs with Vulkan support");

            Span<VkPhysicalDevice> nativePhysicalDevices = stackalloc VkPhysicalDevice[(int)physicalDevicesCount];
            defaultInstance.NativeInstanceApi.vkEnumeratePhysicalDevices(defaultInstance.NativeInstance, nativePhysicalDevices).CheckResult();
            
            var adapterList = new List<GraphicsAdapter>();
            for (int index = 0; index < nativePhysicalDevices.Length; index++)
            {
                VkPhysicalDeviceProperties properties;
                defaultInstance.NativeInstanceApi.vkGetPhysicalDeviceProperties(nativePhysicalDevices[index], out properties);

                // VK_KHR_driver_properties (core in 1.2) exposes driver identity strings the packed driverVersion can't carry.
                VkPhysicalDeviceDriverProperties driverProps = new() { sType = VkStructureType.PhysicalDeviceDriverProperties };
                VkPhysicalDeviceProperties2 properties2 = new() { sType = VkStructureType.PhysicalDeviceProperties2, pNext = &driverProps };
                if (properties.apiVersion >= VkVersion.Version_1_2)
                    defaultInstance.NativeInstanceApi.vkGetPhysicalDeviceProperties2(nativePhysicalDevices[index], &properties2);

                var adapter = new GraphicsAdapter(nativePhysicalDevices[index], properties, driverProps, index);
                staticCollector.Add(adapter);

View on GitHub (pinned to 96fad776d2)