{"record":{"id":"9d98a63303b2178d","repo":"stride3d/stride","slug":"could-not-locate-or-load-native-library-libraryname","errorCode":null,"errorMessage":"Could not locate or load native library ${libraryName}","messagePattern":"Could not locate or load native library (.+?)","errorType":"exception","errorClass":"DllNotFoundException","httpStatus":null,"severity":"critical","filePath":"sources/core/Stride.Core/Native/NativeLibraryHelper.cs","lineNumber":255,"sourceCode":"                    if (NativeLibrary.TryLoad(libraryFilename!, out nint result))\n                    {\n                        return AddLoadedLibrary(libraryName, result);\n                    }\n                }\n            }\n\n            // Finally, try the default loading mechanism (https://docs.microsoft.com/en-us/dotnet/core/dependency-loading/loading-unmanaged)\n            if (NativeLibrary.TryLoad(libraryName, ownerType.Assembly, searchPath: null, out nint handle))\n            {\n                return AddLoadedLibrary(libraryName, handle);\n            }\n\n            // Attempt to load it from PATH\n            nint envHandle = TryLoadFromEnvironment(libraryNameWithExtension);\n            if (envHandle != 0)\n                return envHandle;\n\n            throw new DllNotFoundException($\"Could not locate or load native library {libraryName}\");\n        }\n\n        //\n        // Attempts to load the library from the paths defined in the environment's PATH variable.\n        // Returns the loaded handle, or 0 if not found.\n        //\n        nint TryLoadFromEnvironment(string libraryNameWithExtension)\n        {\n            var envPaths = Environment.GetEnvironmentVariable(\"PATH\")!.Split(Path.PathSeparator);\n            foreach (var pathDir in envPaths)\n            {\n                var libraryFilePath = Path.Combine(pathDir, libraryNameWithExtension);\n                if (NativeLibrary.TryLoad(libraryFilePath, out var result))\n                    return AddLoadedLibrary(libraryName, result);\n            }\n\n            // Not found\n            return 0;","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/core/Stride.Core/Native/NativeLibraryHelper.cs#L237-L273","documentation":"NativeLibraryHelper.PreloadLibrary throws DllNotFoundException when a native (unmanaged) library cannot be loaded by name, by full path, or from any PATH entry after exhausting all fallback strategies (including TryLoadFromEnvironment). Stride preloads native libraries so P/Invoke calls resolve; if preloading fails, dependent native interop will fail. The exception names the library that could not be located.","triggerScenarios":"Calling NativeLibraryHelper.PreloadLibrary(libraryName, ...) when the native binary (e.g. libstride-native.dll / .so / .dylib) is not beside the executable, not in any PATH directory, not loadable via the environment-provided path, and not loadable by the OS loader under the given name.","commonSituations":"Publishing with trimming/SingleFile and native assets not copied to output; copying managed DLLs without the matching native binaries; wrong runtime identifier (linux-x64 vs linux-arm64); missing system dependencies of the native lib; running on an OS/arch the native package does not ship.","solutions":["Verify the native library file exists next to the executable (or in a PATH directory) with the correct platform extension (.dll/.so/.dylib) and architecture.","Set the environment variable Stride uses to point at the library (TryLoadFromEnvironment honors it) or add its directory to PATH / LD_LIBRARY_PATH.","Reinstall/repair the Stride NuGet packages so native runtime assets are restored for the target RID.","Use ldd/Dependencies/dyld tools to check the native lib's own transitive dependencies are present."],"exampleFix":"// before: native lib never copied for the RID\ndotnet publish -r linux-musl-x64 ...\n// after: publish for a RID Stride ships natives for\ndotnet publish -r linux-x64 --self-contained ...\n// or explicitly point the loader at the library\nEnvironment.SetEnvironmentVariable(\"STRIDE_NATIVE_LIBRARY_PATH\", \"/opt/stride/lib\");","handlingStrategy":"fallback","validationCode":"var path = Path.Combine(AppContext.BaseDirectory, NativeLibraryHelper.GetPlatformLibraryName(\"stride-native\"));\nif (!File.Exists(path)) throw new FileNotFoundException($\"Native library missing from output: {path}\");","typeGuard":null,"tryCatchPattern":"try { NativeLibraryHelper.PreloadLibrary(\"stride-native\"); }\ncatch (DllNotFoundException ex)\n{\n    // log ex.Message (contains library name), verify RID/native assets, then rethrow or fail fast\n}","preventionTips":["Publish with explicit RuntimeIdentifier matching the native packages you restore.","Add a post-build check that expected native binaries exist in the output folder.","Keep the environment variable / PATH strategy documented for custom deployment layouts.","Run ldd/Dependencies checks in CI for the packaged native library."],"tags":["native-library","dll-not-found","pinvoke","loading"],"backgroundTag":"resource-not-found","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"}