stride3d/stride · error · NotSupportedException

Vulkan: Device supports only Vulkan

Error message

Vulkan: Device supports only Vulkan {Adapter.DriverInfo.ApiVersion}, but Stride requires Vulkan 1.3.

What it means

Stride's Vulkan backend requires Vulkan 1.3 core (dynamic rendering, synchronization2, timeline semaphores). During device creation it compares Adapter.NativeApiVersion against VkVersion.Version_1_3 and throws NotSupportedException if the physical device supports less.

Solutions

Update the GPU driver to a Vulkan 1.3-compliant release
Select a different adapter via GraphicsAdapterFactory that supports Vulkan 1.3
Upgrade the GPU/hardware if the device caps at an older Vulkan version
On Linux, update mesa to a recent version for newer Vulkan support

Defensive patterns

Strategy: validation

Validate before calling

GraphicsAdapterFactory.Initialize();
foreach (var adapter in GraphicsAdapterFactory.Adapters)
{
    if (adapter.NativeApiVersion < VkVersion.Version_1_3)
        continue; // skip adapters without Vulkan 1.3
    SelectAdapter(adapter);
    break;
}

Type guard

static bool SupportsVulkan13(GraphicsAdapter a) => a.NativeApiVersion >= VkVersion.Version_1_3;

Try / catch

try
{
    var device = new GraphicsDevice(adapter, ...);
}
catch (NotSupportedException ex) when (ex.Message.Contains("Vulkan 1.3"))
{
    Logger.Error(ex, "Adapter lacks Vulkan 1.3; trying next adapter.");
    TryNextAdapter();
}

Prevention

Enumerate adapters and filter by NativeApiVersion before device creation
Publish minimum Vulkan 1.3 GPU requirements
Update drivers on target/test machines
On hybrid-GPU laptops, explicitly select the discrete adapter

When it happens

Trigger: Creating a GraphicsDevice on a physical device whose max supported API version is below 1.3 (e.g. an old GPU or driver reporting Vulkan 1.1/1.2).

Common situations: Older GPUs (pre-2015 era) or drivers never updated to 1.3; laptops with hybrid graphics where the wrong (older) adapter is selected; Android devices with 1.1-only drivers; outdated Linux mesa drivers.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/Vulkan/GraphicsDevice.Vulkan.cs:496

                VK_KHR_SAMPLER_YCBCR_CONVERSION_EXTENSION_NAME,
                VK_KHR_DEDICATED_ALLOCATION_EXTENSION_NAME,
                VK_KHR_GET_MEMORY_REQUIREMENTS_2_EXTENSION_NAME,
                VK_KHR_BIND_MEMORY_2_EXTENSION_NAME,
                VK_EXT_QUEUE_FAMILY_FOREIGN_EXTENSION_NAME,
#endif
            };

            var availableExtensionProperties = GetAvailableExtensionProperties(supportedExtensionProperties);
            ValidateExtensionPropertiesAvailability(availableExtensionProperties);
            var desiredExtensionProperties = new HashSet<VkUtf8String>();

            // Swapchain extension is only needed for presentation (not for headless/asset compilation)
            if (availableExtensionProperties.Contains(VK_KHR_SWAPCHAIN_EXTENSION_NAME))
                desiredExtensionProperties.Add(VK_KHR_SWAPCHAIN_EXTENSION_NAME);

            // Stride uses Vulkan 1.3 core features and entry points
            if (Adapter.NativeApiVersion < VkVersion.Version_1_3)
                throw new NotSupportedException($"Vulkan: Device supports only Vulkan {Adapter.DriverInfo.ApiVersion}, but Stride requires Vulkan 1.3.");

            // Vulkan portability spec: if VK_KHR_portability_subset is advertised, the app MUST enable it.
            // MoltenVK is the only ICD that advertises it; conformant drivers do not.
            bool isPortabilitySubsetDevice = availableExtensionProperties.Contains(VK_KHR_PORTABILITY_SUBSET_EXTENSION_NAME);
            if (isPortabilitySubsetDevice)
                desiredExtensionProperties.Add(VK_KHR_PORTABILITY_SUBSET_EXTENSION_NAME);

#if STRIDE_PLATFORM_IOS || STRIDE_PLATFORM_MACOS
            // VK_EXT_metal_objects lets us import IOSurface-backed CVPixelBuffers as VkImages for
            // zero-copy video upload. MoltenVK 1.2+ supports it; no extra dependency extensions needed.
            HasMetalObjectsSupport = availableExtensionProperties.Contains(VK_EXT_METAL_OBJECTS_EXTENSION_NAME);
            if (HasMetalObjectsSupport)
                desiredExtensionProperties.Add(VK_EXT_METAL_OBJECTS_EXTENSION_NAME);
#endif

#if STRIDE_PLATFORM_ANDROID
            // All extensions in the AHardwareBuffer → VkImage chain must be present together.
            HasAndroidHardwareBufferSupport =

View on GitHub (pinned to 96fad776d2)