{"record":{"id":"fefd9de647b87cc2","repo":"github/copilot-sdk","slug":"failed-to-load-ffi-runtime-library-librarypath","errorCode":null,"errorMessage":"Failed to load FFI runtime library '{libraryPath}'.","messagePattern":"Failed to load FFI runtime library '(.+?)'\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"dotnet/src/FfiRuntimeHost.cs","lineNumber":435,"sourceCode":"    private static void PrepareNativeLibrary(string libraryPath)\n    {\n        lock (NativeLock)\n        {\n            if (s_loaded)\n            {\n                if (s_loadedPath != libraryPath)\n                {\n                    throw new InvalidOperationException(\n                        $\"An in-process FFI runtime library is already loaded from '{s_loadedPath}'; \"\n                        + $\"loading a different library from '{libraryPath}' in the same process is not supported.\");\n                }\n                return;\n            }\n\n            var handle = NativeLoader.Load(libraryPath);\n            if (handle == IntPtr.Zero)\n            {\n                throw new InvalidOperationException($\"Failed to load FFI runtime library '{libraryPath}'.\");\n            }\n\n            s_hostStart = Bind<HostStartDelegate>(handle, \"copilot_runtime_host_start\");\n            s_hostShutdown = Bind<HostShutdownDelegate>(handle, \"copilot_runtime_host_shutdown\");\n            s_connectionOpen = Bind<ConnectionOpenDelegate>(handle, \"copilot_runtime_connection_open\");\n            s_connectionWrite = Bind<ConnectionWriteDelegate>(handle, \"copilot_runtime_connection_write\");\n            s_connectionClose = Bind<ConnectionCloseDelegate>(handle, \"copilot_runtime_connection_close\");\n            s_loaded = true;\n            s_loadedPath = libraryPath;\n        }\n    }\n\n    private static T Bind<T>(IntPtr handle, string export) where T : Delegate\n    {\n        var symbol = NativeLoader.GetSymbol(handle, export);\n        if (symbol == IntPtr.Zero)\n        {\n            throw new InvalidOperationException($\"FFI runtime library is missing the '{export}' export.\");","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/dotnet/src/FfiRuntimeHost.cs#L417-L453","documentation":"NativeLoader.Load returned IntPtr.Zero, meaning the OS/loader could not load the FFI runtime library at the given path. PrepareNativeLibrary wraps this in InvalidOperationException naming the path, before any exports are bound.","triggerScenarios":"Create with a libraryPath whose file is missing, is the wrong architecture (x86 vs x64), has unresolved native dependencies, or lacks read/execute permissions.","commonSituations":"Runtime native binary not deployed alongside the app; wrong RID-specific binary packaged; missing VC++ runtime / libstdc++ on the machine; path pointing at a managed DLL instead of the native one.","solutions":["Confirm the file exists at libraryPath and is the native runtime binary for the current OS/architecture.","Install missing native dependencies (VC++ redistributable, libc/libstdc++) required by the runtime.","Fix permissions so the process can read and map the library.","Ensure the correct RID-specific runtime is included in your build/publish output.","Check loader diagnostics (e.g. Dependencies tool on Windows, ldd on Linux) for unresolved imports."],"exampleFix":"// before\nvar lib = Path.Combine(appDir, \"copilot_runtime.dll\"); // not published\n// after\nvar lib = NativeRuntimeLocator.Resolve(); // verifies File.Exists + arch before Load","handlingStrategy":"try-catch","validationCode":"if (!File.Exists(libraryPath)) throw new FileNotFoundException(\"FFI runtime not found\", libraryPath);\n// optionally pre-check architecture with a PE/ELF header probe","typeGuard":"bool LoadableLibrary(string p) => File.Exists(p) && new FileInfo(p).Length > 0 && MatchesCurrentArch(p);","tryCatchPattern":"try { host = FfiRuntimeHost.Create(libraryPath); }\ncatch (InvalidOperationException ex) when (ex.Message.StartsWith(\"Failed to load FFI runtime library\")) {\n    logger.LogError(ex, \"Could not load native runtime at {Path}\", libraryPath);\n    throw new ApplicationException(\"Install/repair the native runtime for this OS+arch.\", ex);\n}","preventionTips":["Include RID-specific native binaries in publish output","Verify OS/arch before deployment (CI matrix)","Install required native dependencies (VC++ redist, libstdc++)","Check the file is the native runtime, not a managed assembly"],"tags":["ffi","native-library","dll-not-found","load-failure"],"backgroundTag":"file-not-found","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}