stride3d/stride · error · InvalidOperationException

Could not load shader

Error message

Could not load shader [{className}]

What it means

SpirvBuilder.GetOrLoadShader asks the IExternalShaderLoader to load a precompiled shader buffer by class name and macro defines. When the loader cannot return a buffer for the requested class, the builder throws InvalidOperationException to abort compilation. It indicates the shader class name or macro combination does not resolve to any loadable external shader.

Solutions

1. Verify the className exactly matches a shader class registered with the IExternalShaderLoader (check spelling and namespace)
2. Ensure the shader source/asset is loaded/registered before GetOrLoadShader is called
3. Confirm the ShaderMacro defines passed match those used when the shader was compiled/cached
4. Inspect the loader's LoadExternalBuffer implementation/logging to see why the lookup failed
5. Check that required shader assets exist in the deployment output directory

Example fix

// before
var buffers = SpirvBuilder.GetOrLoadShader(loader, "MyShderClass", defines, out hash, out fromCache);
// after
var buffers = SpirvBuilder.GetOrLoadShader(loader, "MyShaderClass", defines, out hash, out fromCache);

// Before compiling, ensure the shader class exists and the loader can resolve it
if (!shaderLoader.TryResolveShaderClass(className, defines))
    throw new ArgumentException($"Unknown shader class '{className}' for defines [{string.Join(",", defines.Select(d => d.Name))}]");

bool IsKnownShader(IExternalShaderLoader l, string name, ReadOnlySpan<ShaderMacro> defines) => l.LoadExternalBuffer(name, defines, out _, out _, out _);

try { var buffers = SpirvBuilder.GetOrLoadShader(loader, className, defines, out var hash, out var cached); }
catch (InvalidOperationException ex) { Log.Error(ex, "Shader '{Class}' not loadable with current defines", className); throw new ShaderCompilationException(className, defines, ex); }

When it happens

Trigger: Calling SpirvBuilder.GetOrLoadShader (directly or via shader compilation) with a className that the external loader does not recognize, or with defines that match no cached/registered shader; LoadExternalBuffer returns false.

Common situations: Typo in shader class name passed to a effect/shader reference; shader source not registered with the external loader; mismatched ShaderMacro set so the cache lookup key differs; shader asset missing at runtime/deployment.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• OpCode not supported when compiling constant
• Unsupported execution model
• Struct not found in shader
• Cannot find instruction for id
• Unsupported base type

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

Appendix: source

Thrown at sources/shaders/Stride.Shaders.Parsers/Spirv/Building/Builder.Class.cs:928

        for (var index = 0; index < shader.Count; index++)
        {
            var i = shader[index];
            if (i.Op == Op.OpGenericParameterSDSL && (OpGenericParameterSDSL)i is { } genericParameter)
            {
                generics.Add(genericParameter.ResultId);
                SetOpNop(i.Data.Memory.Span);
            }
        }

        return generics;
    }

    public static ShaderBuffers GetOrLoadShader(IExternalShaderLoader shaderLoader, string className, ReadOnlySpan<ShaderMacro> defines, out ObjectId hash, out bool isFromCache)
    {
        //Console.WriteLine($"[Shader] Requesting non-generic class {className}");

        if (!shaderLoader.LoadExternalBuffer(className, defines, out var buffer, out hash, out isFromCache))
            throw new InvalidOperationException($"Could not load shader [{className}]");

        //if (!isFromCache)
        //    Console.WriteLine($"[Shader] Loading non-generic class {className} for 1st time");

        return buffer;
    }
}

View on GitHub (pinned to 96fad776d2)