stride3d/stride · error · InvalidOperationException

failed

Error message

{call} failed: {result}

What it means

Check() is the test helper that maps Vulkan API return codes to exceptions in the FrameRenderer.Vulkan test harness. Any vk* call returning something other than VkResult.Success is wrapped in an InvalidOperationException including the call expression and the VkResult. It is a generic gateway error — the actual cause is the specific Vulkan function that failed.

Solutions

1. Install/repair a Vulkan runtime and vendor ICD (vulkaninfo should list a device)
2. Set VK_ICD_FILENAMES/VK_LOADER_DEBUG to diagnose loader failures
3. Enable the harness's software-rendering path (Lavapipe) when no GPU is available
4. Read the VkResult in the message and look up the specific Vulkan error code

Example fix

// before
Check(api.vkCreateInstance(&ci, null, out instance));
// after
var result = api.vkCreateInstance(&ci, null, out instance);
if (result != VkResult.Success)
    Console.WriteLine($"vkCreateInstance failed: {result}; loader debug: {Environment.GetEnvironmentVariable("VK_LOADER_DEBUG")}");
Check(result);

try
{
    Check(api.vkCreateInstance(&ci, null, out instance));
}
catch (InvalidOperationException ex) when (ex.Message.Contains("failed:"))
{
    logger.LogError(ex, "Vulkan call failed; VK_LOADER_DEBUG={Dbg}", Environment.GetEnvironmentVariable("VK_LOADER_DEBUG"));
    throw;
}

When it happens

Trigger: Any Vulkan call routed through Check failing: instance/device creation, vkEnumeratePhysicalDevices, buffer creation etc., returning errors like VK_ERROR_INITIALIZATION_FAILED, VK_ERROR_OUT_OF_HOST_MEMORY, or IncompatibleDriver.

Common situations: Running tests on machines without a Vulkan loader/runtime; missing or incompatible GPU drivers; CI containers with no GPU or ICD files; requesting device features/versions the driver lacks.

Related errors

• Could not locate native executable
• Could not locate native library
• No [UITest] class found in
• No [UITest] class named
• Multiple [UITest] classes in

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

Appendix: source

Thrown at sources/shaders/Stride.Shaders.Tests/FrameRenderer.Vulkan.cs:60

    private VkDescriptorPool descriptorPool;
    private VkDescriptorSet descriptorSet;
    private VkPipelineLayout pipelineLayout;

    // Everything created during a test, destroyed in PresentAndFinish
    private readonly List<VkBuffer> buffers = [];
    private readonly List<VkBufferView> bufferViews = [];
    private readonly List<VkImage> images = [];
    private readonly List<VkImageView> imageViews = [];
    private readonly List<VkSampler> samplers = [];
    private readonly List<VkDeviceMemory> memories = [];
    private readonly List<VkPipeline> pipelines = [];
    private readonly List<VkRenderPass> renderPasses = [];
    private readonly List<VkFramebuffer> framebuffers = [];

    private static void Check(VkResult result, [CallerArgumentExpression(nameof(result))] string call = null)
    {
        if (result != VkResult.Success)
            throw new InvalidOperationException($"{call} failed: {result}");
    }

    private static bool? available;

    /// <summary>
    /// Whether a usable Vulkan 1.2+ device exists (loader present, instance and device selection succeed).
    /// </summary>
    public static bool CheckAvailable()
    {
        if (available == null)
        {
            try
            {
                EnsureSharedContext();
                available = true;
            }
            catch
            {

View on GitHub (pinned to 96fad776d2)