{"record":{"id":"0c0a300d568b3b73","repo":"stride3d/stride","slug":"could-not-locate-native-library-libraryname","errorCode":null,"errorMessage":"Could not locate native library ${libraryName}","messagePattern":"Could not locate native library (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"sources/core/Stride.Core/Native/NativeLibraryHelper.cs","lineNumber":156,"sourceCode":"        {\n            var nameWithExtension = name + libExtension;\n\n            // Resolver-registered natives: the extension-less map is keyed by SONAME-stripped base name\n            // (matches libassimp.so.6); the with-extension map only matches an exact unversioned filename.\n            if (nativeDependenciesWithoutExtensions.TryGetValue(name, out string? knownPath)\n                || nativeDependenciesWithExtensions.TryGetValue(nameWithExtension, out knownPath))\n                return knownPath;\n\n            // Try in current path\n            if (File.Exists(nameWithExtension))\n                return nameWithExtension;\n\n            // Try runtimes specific path (globs SONAME-versioned variants, picks highest)\n            if (TryFindLibraryPath(ownerType, nameWithExtension, out knownPath))\n                return knownPath;\n        }\n\n        throw new FileNotFoundException($\"Could not locate native library {libraryName}\");\n    }\n\n    /// <summary>\n    ///   Preloads a native library (or returns the handle of one already loaded), so subsequent P/Invoke\n    ///   calls use it instead of triggering their own load. The returned OS module handle also lets callers\n    ///   that resolve exports themselves (for example, libraries with their own function-pointer binding)\n    ///   share the engine's native resolution.\n    /// </summary>\n    /// <param name=\"libraryName\">The name of the library, without the extension.</param>\n    /// <param name=\"ownerType\">\n    ///   The <see cref=\"Type\"/> whose Assembly location is related to the native library.\n    ///   This is needed because <see cref=\"Assembly.GetCallingAssembly\"/> cannot be used,\n    ///   as it might be wrong due to optimizations.\n    /// </param>\n    /// <returns>The OS module handle of the loaded library.</returns>\n    /// <exception cref=\"DllNotFoundException\">\n    ///   The library with name <paramref name=\"libraryName\"/> could not be loaded.\n    /// </exception>","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/core/Stride.Core/Native/NativeLibraryHelper.cs#L138-L174","documentation":"LocateLibrary throws FileNotFoundException when a native library (name plus the platform extension .dll/.so/.dylib, including 'lib'-prefixed and SONAME-versioned variants on Unix) cannot be found in the packaged native-dependency cache or under the owner assembly's runtimes/{platform}-{cpu}/native folder. It indicates the native dependency required for P/Invoke is absent from the deployment.","triggerScenarios":"Calling NativeLibraryHelper.LocateLibrary(libraryName, ownerType) where neither 'libraryName.ext' nor, on non-Windows, 'liblibraryName.ext' (nor SONAME-versioned variants) exists next to the owner assembly or in its runtimes-specific native folder.","commonSituations":"Linux deployment where the .so was not packaged for linux-x64; library renamed or version-bumped (libfoo.so.6 vs libfoo.so.7 mismatch); self-contained publish that trimmed native assets; running tests from a directory lacking the runtimes layout; package depends on a system library the user hasn't installed.","solutions":["Confirm the native library for the current RID exists next to the owner assembly (runtimes/{rid}/native/libname.so / name.dll / libname.dylib).","Ensure the NuGet package ships native assets for all target RIDs or install the matching runtime pack.","On Linux/macOS, verify SONAME-versioned files are present (e.g. libassimp.so.5) since the helper globs variants but needs at least one to exist.","Catch FileNotFoundException and either load from a user-configured path via NativeLibrary.Load or produce an install instruction message.","Check the library name spelling/casing and whether the 'lib' prefix convention is met."],"exampleFix":"// before\nvar path = NativeLibraryHelper.LocateLibrary(\"assimp\", typeof(App)); // FileNotFoundException on slim publish\n// after\nstring path;\ntry { path = NativeLibraryHelper.LocateLibrary(\"assimp\", typeof(App)); }\ncatch (FileNotFoundException ex)\n{\n    throw new InvalidOperationException(\n        \"Native library 'assimp' missing. Ensure the Stride native assets package for \" +\n        $\"{RuntimeInformation.RuntimeIdentifier} is referenced.\", ex);\n}","handlingStrategy":"try-catch","validationCode":"static bool NativeLibPresent(string lib, Type owner)\n{\n    var ext = OperatingSystem.IsWindows() ? \".dll\" : OperatingSystem.IsMacOS() ? \".dylib\" : \".so\";\n    var rid = RuntimeInformation.RuntimeIdentifier;\n    var dir = Path.Combine(AppContext.BaseDirectory, \"runtimes\", rid, \"native\");\n    return File.Exists(Path.Combine(dir, lib + ext)) || File.Exists(Path.Combine(dir, \"lib\" + lib + ext));\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    libPath = NativeLibraryHelper.LocateLibrary(libraryName, ownerType);\n}\ncatch (FileNotFoundException ex)\n{\n    throw new InvalidOperationException(\n    $\"Native library '{libraryName}' not found for {RuntimeInformation.RuntimeIdentifier}. Install the matching native assets package.\", ex);\n}","preventionTips":["Ensure native runtimes assets are included in publish (don't strip runtimes/ folder).","Keep SONAME-versioned files (libfoo.so.N) alongside the .so on Unix.","Match library names/casing against package contents; remember the automatic 'lib' prefix attempt on Unix.","Add per-RID integration tests that call LocateLibrary for every native dependency."],"tags":["native-interop","file-not-found","nuget","deployment"],"backgroundTag":"file-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"}