stride3d/stride · critical · NotSupportedException

Shader Compilation is not allowed at run time on this…

Error message

Shader Compilation is not allowed at run time on this platform.

What it means

NullEffectCompiler is a placeholder compiler used on platforms that forbid runtime shader compilation. Its Compile always throws NotSupportedException: all effects must have been precompiled at build time and loaded from the bytecode cache instead.

Solutions

Precompile all effect permutations at build time (Stride Game Studio effect compilation) and ship the bytecode cache.
Ensure the runtime file provider is mounted on the compiled-effects database so the cache resolves bytecode before hitting the null compiler.
Use a real compiler (EffectCompiler/EffectCompilerCache) in editor/tooling scenarios.
Remove or statically declare dynamically generated shader permutations so they get precompiled.

Example fix

// before
var compiler = new NullEffectCompiler(); // then compiler.Compile(mixin, ...) throws
// after (build-time)
var compiler = new EffectCompilerCache(new EffectCompiler(fileProvider), databaseFileProvider);
// runtime: load precompiled bytecode instead of compiling

Defensive patterns

Strategy: fallback

Validate before calling

if (compiler is NullEffectCompiler) throw new InvalidOperationException("Runtime shader compilation unavailable; ensure effects were precompiled and the bytecode cache is mounted");

Type guard

bool IsRuntimeNullCompiler(EffectCompilerBase c) => c is NullEffectCompiler;

Try / catch

try { bytecode = compiler.Compile(mixin, parameters, compilerParameters, hash); } catch (NotSupportedException ex) when (ex.Message.Contains("not allowed at run time")) { /* load precompiled bytecode from cache or fail deployment check */ }

Prevention

Precompile all effect permutations in the build pipeline
Mount the compiled-effects database at startup on runtime-only platforms
Never use NullEffectCompiler in editor/tool scenarios
Add a deployment smoke test that loads every effect

When it happens

Trigger: Any call path reaching NullEffectCompiler.Compile at runtime — requesting an effect whose bytecode is not in the cache on a runtime-only platform (consoles, some mobile targets), or accidentally wiring NullEffectCompiler in an editor/tool context.

Common situations: Deploying without the precompiled effects database; new shader permutations added after the build-time effect compile; misconfigured compiler factory selecting the null compiler during development.

Related errors

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

Appendix: source

Thrown at sources/shaders/Stride.Shaders.Effects/Compiler/NullEffectCompiler.cs:34

        public NullEffectCompiler(IVirtualFileProvider fileProvider, DatabaseFileProvider database)
        {
            FileProvider = fileProvider;
            this.database = database;
        }

        public override ObjectId GetShaderSourceHash(string type)
        {
            var url = GetStoragePathFromShaderType(type);
            var shaderSourceId = ObjectId.Empty;
            database?.ContentIndexMap.TryGetValue(url, out shaderSourceId);
            return shaderSourceId;
        }

        public override IVirtualFileProvider FileProvider { get; set; }

        public override TaskOrResult<EffectBytecodeCompilerResult> Compile(ShaderMixinSource mixinTree, EffectCompilerParameters effectParameters, CompilerParameters compilerParameters, ObjectId effectInputHash)
        {
            throw new NotSupportedException("Shader Compilation is not allowed at run time on this platform.");
        }
    }
}

View on GitHub (pinned to 96fad776d2)