stride3d/stride · critical · DllNotFoundException

Could not locate or load native library

Error message

Could not locate or load native library ${libraryName}

What it means

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.

Solutions

1. 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.
2. Set the environment variable Stride uses to point at the library (TryLoadFromEnvironment honors it) or add its directory to PATH / LD_LIBRARY_PATH.
3. Reinstall/repair the Stride NuGet packages so native runtime assets are restored for the target RID.
4. Use ldd/Dependencies/dyld tools to check the native lib's own transitive dependencies are present.

Example fix

// before: native lib never copied for the RID
dotnet publish -r linux-musl-x64 ...
// after: publish for a RID Stride ships natives for
dotnet publish -r linux-x64 --self-contained ...
// or explicitly point the loader at the library
Environment.SetEnvironmentVariable("STRIDE_NATIVE_LIBRARY_PATH", "/opt/stride/lib");

var path = Path.Combine(AppContext.BaseDirectory, NativeLibraryHelper.GetPlatformLibraryName("stride-native"));
if (!File.Exists(path)) throw new FileNotFoundException($"Native library missing from output: {path}");

try { NativeLibraryHelper.PreloadLibrary("stride-native"); }
catch (DllNotFoundException ex)
{
    // log ex.Message (contains library name), verify RID/native assets, then rethrow or fail fast
}

When it happens

Trigger: 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.

Common situations: 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.

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

• FFmpeg library ' ' was not loaded.
• Error while pre-loading package
• Could not find function

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

Appendix: source

Thrown at sources/core/Stride.Core/Native/NativeLibraryHelper.cs:255

                    if (NativeLibrary.TryLoad(libraryFilename!, out nint result))
                    {
                        return AddLoadedLibrary(libraryName, result);
                    }
                }
            }

            // Finally, try the default loading mechanism (https://docs.microsoft.com/en-us/dotnet/core/dependency-loading/loading-unmanaged)
            if (NativeLibrary.TryLoad(libraryName, ownerType.Assembly, searchPath: null, out nint handle))
            {
                return AddLoadedLibrary(libraryName, handle);
            }

            // Attempt to load it from PATH
            nint envHandle = TryLoadFromEnvironment(libraryNameWithExtension);
            if (envHandle != 0)
                return envHandle;

            throw new DllNotFoundException($"Could not locate or load native library {libraryName}");
        }

        //
        // Attempts to load the library from the paths defined in the environment's PATH variable.
        // Returns the loaded handle, or 0 if not found.
        //
        nint TryLoadFromEnvironment(string libraryNameWithExtension)
        {
            var envPaths = Environment.GetEnvironmentVariable("PATH")!.Split(Path.PathSeparator);
            foreach (var pathDir in envPaths)
            {
                var libraryFilePath = Path.Combine(pathDir, libraryNameWithExtension);
                if (NativeLibrary.TryLoad(libraryFilePath, out var result))
                    return AddLoadedLibrary(libraryName, result);
            }

            // Not found
            return 0;

View on GitHub (pinned to 96fad776d2)