stride3d/stride · critical · InvalidOperationException

Failed to create vulkan instance

Error message

Failed to create vulkan instance: {result}

What it means

Stride calls vkCreateInstance when constructing its internal GraphicsAdapterFactoryInstance. If the call returns anything other than VK_SUCCESS (e.g. VK_ERROR_OUT_OF_HOST_MEMORY, VK_ERROR_LAYER_NOT_PRESENT, VK_ERROR_EXTENSION_NOT_PRESENT), it throws InvalidOperationException with the raw VkResult in the message.

Solutions

1. Check the reported VkResult: VK_ERROR_LAYER_NOT_PRESENT/EXTENSION_NOT_PRESENT means requested layers/extensions are unavailable — remove or make them optional
2. Install the missing Vulkan layers (Vulkan SDK / vulkan-validationlayers package) if validation is required
3. Repair or reinstall the GPU driver and Vulkan runtime
4. Retry after freeing memory if the result is VK_ERROR_OUT_OF_HOST/DEVICE_MEMORY

Example fix

// before
InstanceExtensions = all extensions including optional ones
// after
InstanceExtensions = requiredExtensions.Intersect(EnumerateAvailableExtensions()); // only enable what exists

// only enable layers/extensions that are actually available
var available = EnumerateInstanceExtensions();
requestedExtensions = required.Where(e => available.Contains(e));

try { GraphicsAdapterFactory.Initialize(); } catch (InvalidOperationException ex) when (ex.Message.StartsWith("Failed to create vulkan instance:")) { /* inspect VkResult; disable optional layers/extensions and retry */ }

When it happens

Trigger: Requesting unavailable instance layers/extensions in CreateInstance (validation layers not installed, missing VK_KHR_surface extensions), or loader failures due to corrupt/absent Vulkan runtime; result != VK_SUCCESS after vkCreateInstance.

Common situations: Enabling VK_LAYER_KHRONOS_validation on machines without the Vulkan SDK; requesting extensions removed in a newer loader; broken driver installation; out-of-memory on constrained systems.

Related errors

• Vulkan: Failed to find GPUs with Vulkan support
• Required extension is not available
• Vulkan: Device supports only Vulkan
• 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/5d601b074cd4bee9. Report an issue: GitHub.

Appendix: source

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

                    pSettingName = pMvkLogLevelKey,
                    type = VkLayerSettingTypeEXT.Int32,
                    valueCount = 1,
                    pValues = &mvkLogLevel,
                };
                var layerSettings = new VkLayerSettingsCreateInfoEXT
                {
                    sType = VkStructureType.LayerSettingsCreateInfoEXT,
                    settingCount = 1,
                    pSettings = &mvkLogLevelSetting,
                };
                if ((Platform.Type == PlatformType.macOS || Platform.Type == PlatformType.iOS)
                    && Environment.GetEnvironmentVariable("MVK_CONFIG_LOG_LEVEL") == null)
                    instanceCreateInfo.pNext = &layerSettings;

                result = vkCreateInstance(&instanceCreateInfo, out NativeInstance);
            }
            if (result != VK_SUCCESS)
                throw new InvalidOperationException($"Failed to create vulkan instance: {result}");

            NativeInstanceApi = GetApi(NativeInstance);

            // Create debug messenger only if the extension was actually enabled and the function is available.
            // The Vulkan loader may advertise VK_EXT_debug_utils but fail to provide the function
            // if no validation layers are installed.
            if (enableDebugUtils && NativeInstanceApi.vkCreateDebugUtilsMessengerEXT_ptr != default)
            {
                var createInfo = new VkDebugUtilsMessengerCreateInfoEXT
                {
                    sType = VkStructureType.DebugUtilsMessengerCreateInfoEXT,
                    messageSeverity = VkDebugUtilsMessageSeverityFlagsEXT.Verbose | VkDebugUtilsMessageSeverityFlagsEXT.Info | VkDebugUtilsMessageSeverityFlagsEXT.Error | VkDebugUtilsMessageSeverityFlagsEXT.Warning,
                    messageType = VkDebugUtilsMessageTypeFlagsEXT.General | VkDebugUtilsMessageTypeFlagsEXT.Validation | VkDebugUtilsMessageTypeFlagsEXT.Performance,
                    pfnUserCallback = &DebugReport
                };

                NativeInstanceApi.vkCreateDebugUtilsMessengerEXT(NativeInstance, &createInfo, null, out debugReportCallback).CheckResult();
            }

View on GitHub (pinned to 96fad776d2)