{"record":{"id":"f23c8357be57a872","repo":"stride3d/stride","slug":"could-not-locate-native-executable-executablename","errorCode":null,"errorMessage":"Could not locate native executable ${executableName}","messagePattern":"Could not locate native executable (.+?)","errorType":"exception","errorClass":"FileNotFoundException","httpStatus":null,"severity":"error","filePath":"sources/core/Stride.Core/Native/NativeLibraryHelper.cs","lineNumber":111,"sourceCode":"    /// </exception>\n    /// <remarks>\n    ///   This method is typically used to resolve platform-specific native binaries required by managed code.\n    /// </remarks>\n    public static string LocateExecutable(string executableName, Type ownerType)\n    {\n        // NuGet native libraries\n        if (nativeDependenciesWithExtensions.TryGetValue(executableName, out string? knownExePath))\n            return knownExePath;\n\n        // Try in current path\n        if (File.Exists(executableName))\n            return executableName;\n\n        // Try runtimes specific path\n        if (TryFindLibraryPath(ownerType, executableName, out knownExePath))\n            return knownExePath;\n\n        throw new FileNotFoundException($\"Could not locate native executable {executableName}\");\n    }\n\n    /// <summary>\n    ///   Locates the full path to a native library, appending the current platform's library\n    ///   extension (<c>.dll</c>, <c>.so</c>, <c>.dylib</c>) to <paramref name=\"libraryName\"/> before\n    ///   searching. On Linux/macOS, SONAME-versioned variants (for example, <c>libfoo.so.6</c> or\n    ///   <c>libfoo.6.dylib</c>) are matched and the highest version is returned; the <c>lib</c> prefix\n    ///   is also tried when omitted, matching the conventions <see cref=\"PreloadLibrary\"/> uses.\n    /// </summary>\n    /// <param name=\"libraryName\">The library name without extension (for example, <c>\"libassimp\"</c> or <c>\"assimp\"</c>).</param>\n    /// <param name=\"ownerType\">\n    ///   The type whose assembly is used to determine runtime-specific search paths for the library.\n    /// </param>\n    /// <returns>The full path to the located native library.</returns>\n    /// <exception cref=\"FileNotFoundException\">\n    ///   Thrown if the library cannot be found in any of the searched locations.\n    /// </exception>\n    public static string LocateLibrary(string libraryName, Type ownerType)","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/core/Stride.Core/Native/NativeLibraryHelper.cs#L93-L129","documentation":"LocateExecutable throws FileNotFoundException when a native executable cannot be found in any searched location: the NuGet native-dependencies cache, the current working directory, or the owner assembly's runtimes/<rid>/native folder. It signals that a platform-specific binary expected to ship alongside the managed assembly is missing.","triggerScenarios":"Calling NativeLibraryHelper.LocateExecutable(executableName, ownerType) where executableName is neither registered as a packaged native dependency, present in the current directory, nor found under the owner assembly's runtimes/{platform}-{cpu}/native path.","commonSituations":"NuGet package published without the native runtime assets for the current RID (e.g. built for win-x64 but run on linux-x64); executable renamed between package versions; running from a publish output that stripped native tools; wrong working directory when relying on relative-path lookup.","solutions":["Verify the native executable exists under runtimes/{current-rid}/native next to the owner assembly (e.g. runtimes/linux-x64/native/).","Ensure the NuGet package includes native assets for the runtime identifier you deploy to, or add the right runtime pack / runtime.json mappings.","Catch FileNotFoundException and fall back to an explicit path or a clearer error telling the user which native tool to install.","Check that the executable name including extension matches exactly (case-insensitive dictionary lookup but File.Exists on the current path is platform-sensitive)."],"exampleFix":"// before\nvar exe = NativeLibraryHelper.LocateExecutable(\"StrideNativeTool\", typeof(App)); // throws if missing\n// after\nstring exe;\ntry { exe = NativeLibraryHelper.LocateExecutable(\"StrideNativeTool\", typeof(App)); }\ncatch (FileNotFoundException)\n{\n    exe = Path.Combine(AppContext.BaseDirectory, \"tools\", \"StrideNativeTool.exe\");\n    if (!File.Exists(exe)) throw new InvalidOperationException(\"StrideNativeTool is not installed with the application\");\n}","handlingStrategy":"try-catch","validationCode":"static bool CanLocateExecutable(string name, Type owner) =>\n    File.Exists(name) || File.Exists(Path.Combine(AppContext.BaseDirectory, \"runtimes\",\n        $\"{(Platform.Type == PlatformType.Windows ? \"win\" : Platform.Type == PlatformType.Linux ? \"linux\" : \"osx\")}-{RuntimeInformation.ProcessArchitecture.ToString().ToLowerInvariant().Replace(\"x64\",\"x64\")}\", \"native\", name));","typeGuard":null,"tryCatchPattern":"try\n{\n    exePath = NativeLibraryHelper.LocateExecutable(executableName, ownerType);\n}\ncatch (FileNotFoundException ex)\n{\n    throw new InvalidOperationException(\n    $\"Native executable '{executableName}' is missing. Ensure the native assets package for {RuntimeInformation.RuntimeIdentifier} is installed.\", ex);\n}","preventionTips":["Reference the native assets NuGet package and verify runtimes/<rid>/native content after publish.","Publish for explicit RIDs and smoke-test executable resolution on each.","Never rename native executables between package versions without a bump/migration note.","Run with the app directory as working directory if relying on relative lookup."],"tags":["native-interop","file-not-found","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"}