github/copilot-sdk · critical · InvalidOperationException

Failed to load FFI runtime library

Error message

Failed to load FFI runtime library '{libraryPath}'.

What it means

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.

Solutions

  1. Confirm the file exists at libraryPath and is the native runtime binary for the current OS/architecture.
  2. Install missing native dependencies (VC++ redistributable, libc/libstdc++) required by the runtime.
  3. Fix permissions so the process can read and map the library.
  4. Ensure the correct RID-specific runtime is included in your build/publish output.
  5. Check loader diagnostics (e.g. Dependencies tool on Windows, ldd on Linux) for unresolved imports.

Example fix

// before
var lib = Path.Combine(appDir, "copilot_runtime.dll"); // not published
// after
var lib = NativeRuntimeLocator.Resolve(); // verifies File.Exists + arch before Load
Defensive patterns

Strategy: try-catch

Validate before calling

if (!File.Exists(libraryPath)) throw new FileNotFoundException("FFI runtime not found", libraryPath);
// optionally pre-check architecture with a PE/ELF header probe

Type guard

bool LoadableLibrary(string p) => File.Exists(p) && new FileInfo(p).Length > 0 && MatchesCurrentArch(p);

Try / catch

try { host = FfiRuntimeHost.Create(libraryPath); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Failed to load FFI runtime library")) {
    logger.LogError(ex, "Could not load native runtime at {Path}", libraryPath);
    throw new ApplicationException("Install/repair the native runtime for this OS+arch.", ex);
}

Prevention

When it happens

Trigger: Create with a libraryPath whose file is missing, is the wrong architecture (x86 vs x64), has unresolved native dependencies, or lacks read/execute permissions.

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

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/fefd9de647b87cc2. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/FfiRuntimeHost.cs:435

    private static void PrepareNativeLibrary(string libraryPath)
    {
        lock (NativeLock)
        {
            if (s_loaded)
            {
                if (s_loadedPath != libraryPath)
                {
                    throw new InvalidOperationException(
                        $"An in-process FFI runtime library is already loaded from '{s_loadedPath}'; "
                        + $"loading a different library from '{libraryPath}' in the same process is not supported.");
                }
                return;
            }

            var handle = NativeLoader.Load(libraryPath);
            if (handle == IntPtr.Zero)
            {
                throw new InvalidOperationException($"Failed to load FFI runtime library '{libraryPath}'.");
            }

            s_hostStart = Bind<HostStartDelegate>(handle, "copilot_runtime_host_start");
            s_hostShutdown = Bind<HostShutdownDelegate>(handle, "copilot_runtime_host_shutdown");
            s_connectionOpen = Bind<ConnectionOpenDelegate>(handle, "copilot_runtime_connection_open");
            s_connectionWrite = Bind<ConnectionWriteDelegate>(handle, "copilot_runtime_connection_write");
            s_connectionClose = Bind<ConnectionCloseDelegate>(handle, "copilot_runtime_connection_close");
            s_loaded = true;
            s_loadedPath = libraryPath;
        }
    }

    private static T Bind<T>(IntPtr handle, string export) where T : Delegate
    {
        var symbol = NativeLoader.GetSymbol(handle, export);
        if (symbol == IntPtr.Zero)
        {
            throw new InvalidOperationException($"FFI runtime library is missing the '{export}' export.");

View on GitHub (pinned to cd8cf15dc3)