{"record":{"id":"34d80d17050f07ff","repo":"stride3d/stride","slug":"shader-name-could-not-be-loaded","errorCode":null,"errorMessage":"Shader {name} could not be loaded","messagePattern":"Shader (.+?) could not be loaded","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/shaders/Stride.Shaders.Compilers/ShaderLoaderBase.cs","lineNumber":70,"sourceCode":"            isFromCache = false;\n        }\n\n        // Coordinate parallel compilations: only one thread compiles a given (name, macros) pair.\n        var macrosHash = ComputeMacrosHash(defines);\n        var macrosArray = defines.ToArray();\n        var key = (name, macrosHash);\n\n        var lazy = compilingShaders.GetOrAdd(key, _ => new Lazy<(ShaderBuffers, ObjectId)>(() =>\n        {\n            // Double-check cache (another thread may have finished between our check and this factory)\n            if (Cache.TryLoadFromCache(name, null, macrosArray, out var buf, out var h) && ValidateCachedHashes(buf))\n                return (buf, h);\n\n            if (!ExternalFileExists(name))\n                throw new InvalidOperationException($\"Shader {name} could not be found\");\n\n            if (!LoadExternalFileContent(name, out var filename, out var code, out h))\n                throw new InvalidOperationException($\"Shader {name} could not be loaded\");\n\n            if (!LoadFromCode(filename, code, h, macrosArray, out buf))\n                throw new InvalidOperationException($\"Shader {name} could not be compiled\");\n\n            return (buf, h);\n        }, LazyThreadSafetyMode.ExecutionAndPublication));\n\n        try\n        {\n            var result = lazy.Value;\n            buffer = result.Buffer;\n            hash = result.Hash;\n            isFromCache = false;\n            return true;\n        }\n        finally\n        {\n            compilingShaders.TryRemove(key, out _);","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/shaders/Stride.Shaders.Compilers/ShaderLoaderBase.cs#L52-L88","documentation":"In the same lazy factory of ShaderLoaderBase.LoadExternalBuffer, after the file is confirmed to exist, LoadExternalFileContent(name, out filename, out code, out h) is called to read and hash the shader source. A false return here (file exists but its content could not be read/decoded, or hashing failed) triggers \"Shader {name} could not be loaded\". This is the read-failure stage between existence checking and compilation.","triggerScenarios":"ExternalFileExists(name) returns true but LoadExternalFileContent fails: the file cannot be opened, an I/O error occurs, the file provider returns unreadable content, or content hashing fails for the shader source.","commonSituations":"File locked by another process or antivirus; permission issues on the shader directory; partially written/corrupt .sdsl file in the output folder; virtual file system or asset streaming glitch.","solutions":["Check file access permissions and that no other process holds a lock on the .sdsl file.","Re-copy or restore the shader file in the output/source directory (may be truncated or corrupt).","Retry after confirming the shader source directory is reachable (network drive mounted, virtual FS ready).","If you implement a custom source provider, debug LoadExternalFileContent to see why it returns false for this name."],"exampleFix":"// before (locked/corrupt file at shaders/MyShader.sdsl)\nvar buf = loader.LoadExternalBuffer(\"MyShader\", macros, ...); // throws\n// after: ensure the file is unlocked and present, or pre-check\nif (!File.Exists(shaderPath) || !CanRead(shaderPath)) FixOrRestore(shaderPath);\nvar buf = loader.LoadExternalBuffer(\"MyShader\", macros, ...);","handlingStrategy":"retry","validationCode":"var path = Path.Combine(shaderDir, name + \".sdsl\");\nif (!File.Exists(path)) throw new FileNotFoundException(path);\nusing var fs = File.OpenRead(path); // throws earlier with a clearer error if locked","typeGuard":null,"tryCatchPattern":"for (int attempt = 0; attempt < 3; attempt++)\n{\n    try { loader.LoadExternalBuffer(name, macros, out var buf, out var h, out var c); break; }\n    catch (InvalidOperationException ex) when (ex.Message.Contains(\"could not be loaded\") && attempt < 2)\n    { Thread.Sleep(200); } // transient lock/AV scan\n}","preventionTips":["Exclude shader directories from antivirus real-time scanning in build environments.","Don't write shader files in-place while the game/effect compiler is reading them.","Validate shader deployment (file sizes, counts) after build."],"tags":["shader","file-read-failed","shader-loader"],"backgroundTag":"file-read-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"}