{"record":{"id":"5d601b074cd4bee9","repo":"stride3d/stride","slug":"failed-to-create-vulkan-instance-result","errorCode":null,"errorMessage":"Failed to create vulkan instance: {result}","messagePattern":"Failed to create vulkan instance: (.+?)","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs","lineNumber":283,"sourceCode":"                    pSettingName = pMvkLogLevelKey,\n                    type = VkLayerSettingTypeEXT.Int32,\n                    valueCount = 1,\n                    pValues = &mvkLogLevel,\n                };\n                var layerSettings = new VkLayerSettingsCreateInfoEXT\n                {\n                    sType = VkStructureType.LayerSettingsCreateInfoEXT,\n                    settingCount = 1,\n                    pSettings = &mvkLogLevelSetting,\n                };\n                if ((Platform.Type == PlatformType.macOS || Platform.Type == PlatformType.iOS)\n                    && Environment.GetEnvironmentVariable(\"MVK_CONFIG_LOG_LEVEL\") == null)\n                    instanceCreateInfo.pNext = &layerSettings;\n\n                result = vkCreateInstance(&instanceCreateInfo, out NativeInstance);\n            }\n            if (result != VK_SUCCESS)\n                throw new InvalidOperationException($\"Failed to create vulkan instance: {result}\");\n\n            NativeInstanceApi = GetApi(NativeInstance);\n\n            // Create debug messenger only if the extension was actually enabled and the function is available.\n            // The Vulkan loader may advertise VK_EXT_debug_utils but fail to provide the function\n            // if no validation layers are installed.\n            if (enableDebugUtils && NativeInstanceApi.vkCreateDebugUtilsMessengerEXT_ptr != default)\n            {\n                var createInfo = new VkDebugUtilsMessengerCreateInfoEXT\n                {\n                    sType = VkStructureType.DebugUtilsMessengerCreateInfoEXT,\n                    messageSeverity = VkDebugUtilsMessageSeverityFlagsEXT.Verbose | VkDebugUtilsMessageSeverityFlagsEXT.Info | VkDebugUtilsMessageSeverityFlagsEXT.Error | VkDebugUtilsMessageSeverityFlagsEXT.Warning,\n                    messageType = VkDebugUtilsMessageTypeFlagsEXT.General | VkDebugUtilsMessageTypeFlagsEXT.Validation | VkDebugUtilsMessageTypeFlagsEXT.Performance,\n                    pfnUserCallback = &DebugReport\n                };\n\n                NativeInstanceApi.vkCreateDebugUtilsMessengerEXT(NativeInstance, &createInfo, null, out debugReportCallback).CheckResult();\n            }","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Graphics/Vulkan/GraphicsAdapterFactory.Vulkan.cs#L265-L301","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the reported VkResult: VK_ERROR_LAYER_NOT_PRESENT/EXTENSION_NOT_PRESENT means requested layers/extensions are unavailable — remove or make them optional","Install the missing Vulkan layers (Vulkan SDK / vulkan-validationlayers package) if validation is required","Repair or reinstall the GPU driver and Vulkan runtime","Retry after freeing memory if the result is VK_ERROR_OUT_OF_HOST/DEVICE_MEMORY"],"exampleFix":"// before\nInstanceExtensions = all extensions including optional ones\n// after\nInstanceExtensions = requiredExtensions.Intersect(EnumerateAvailableExtensions()); // only enable what exists","handlingStrategy":"try-catch","validationCode":"// only enable layers/extensions that are actually available\nvar available = EnumerateInstanceExtensions();\nrequestedExtensions = required.Where(e => available.Contains(e));","typeGuard":null,"tryCatchPattern":"try { GraphicsAdapterFactory.Initialize(); } catch (InvalidOperationException ex) when (ex.Message.StartsWith(\"Failed to create vulkan instance:\")) { /* inspect VkResult; disable optional layers/extensions and retry */ }","preventionTips":["Make validation layers and optional extensions opt-in, verified against vkEnumerateInstanceLayerProperties/ExtensionProperties","Install the Vulkan SDK where validation is desired","Keep GPU drivers and the Vulkan loader current","Parse the VkResult from the message to distinguish memory vs layer/extension errors"],"tags":["vulkan","instance-creation","initialization","driver"],"backgroundTag":"module-init-failed","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"}