github/copilot-sdk · error · InvalidOperationException

In-process FFI runtime library not found at

Error message

In-process FFI runtime library not found at '<searchedRuntime>'.

What it means

StartAsync throws this InvalidOperationException when the in-process FFI transport cannot locate the native runtime library. GetBundledNativePath searched the expected locations (recorded in 'searchedRuntime') and found nothing, and no explicit CLI path was provided to resolve the library from.

Solutions

1. Check the searched path in the message and verify the native runtime library exists there or next to the app binaries.
2. Set an explicit CLI/runtime path so ResolveRuntimePathForExplicitCli is used instead of the bundled lookup.
3. Reinstall/restore the NuGet package that ships the native runtime, and ensure publish includes native libraries (no aggressive trimming of native assets).
4. Fall back to RuntimeConnection.ForStdio() which spawns the CLI as a child process instead of loading the native library.

Example fix

// before
var client = new CopilotClient(options, RuntimeConnection.ForInProcess()); // runtime lib missing
// after - point at the runtime explicitly, or use stdio
var client = new CopilotClient(options with { CliPath = "/path/to/copilot" }, RuntimeConnection.ForInProcess());
// or
var client = new CopilotClient(options, RuntimeConnection.ForStdio());

var libPath = GetBundledNativePath(FfiRuntimeHost.GetRuntimeLibraryFileName(), out _);
if (libPath is null && explicitCliPath is null)
    Console.Error.WriteLine("Native FFI runtime missing; falling back to stdio transport.");

static bool FfiRuntimeAvailable(string? explicitCliPath) => explicitCliPath is not null || File.Exists(Path.Combine(AppContext.BaseDirectory, FfiRuntimeHost.GetRuntimeLibraryFileName()));

try { client = new CopilotClient(options, RuntimeConnection.ForInProcess()); await client.StartAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("FFI runtime library not found")) { client = new CopilotClient(options, RuntimeConnection.ForStdio()); await client.StartAsync(); }

When it happens

Trigger: Creating a CopilotClient with RuntimeConnection.ForInProcess() and calling StartAsync/EnsureConnectedAsync when the native runtime library was not shipped or is missing from the bundle, and no explicitCliPath was configured.

Common situations: Publishing/trimming a .NET app that dropped the native library from the output; running on an unsupported platform/architecture so the bundled path doesn't match; copying assemblies without the native runtime files; missing NuGet native assets package.

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

• FFI runtime library not found. Looked for
• FFI runtime library not found at
• copilot_runtime_host_start failed
• copilot_runtime_connection_open failed.
• Could not determine a napi-rs prebuilds folder for FFI…

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

Appendix: source

Thrown at dotnet/src/Client.cs:427

                        ffiArgs.Add("--no-auto-login");
                    }
                    if (_options.SessionIdleTimeoutSeconds is > 0)
                    {
                        ffiArgs.AddRange(["--session-idle-timeout", _options.SessionIdleTimeoutSeconds.Value.ToString(CultureInfo.InvariantCulture)]);
                    }
                    if (_options.EnableRemoteSessions)
                    {
                        ffiArgs.Add("--remote");
                    }

                    var explicitCliPath = System.Environment.GetEnvironmentVariable("COPILOT_CLI_PATH");
                    if (string.IsNullOrEmpty(explicitCliPath))
                    {
                        explicitCliPath = null;
                    }
                    var ffiRuntimePath = explicitCliPath is null
                        ? GetBundledNativePath(FfiRuntimeHost.GetRuntimeLibraryFileName(), out var searchedRuntime)
                            ?? throw new InvalidOperationException(
                                $"In-process FFI runtime library not found at '{searchedRuntime}'.")
                        : ResolveRuntimePathForExplicitCli(explicitCliPath);
                    var ffiHost = FfiRuntimeHost.Create(
                        ffiRuntimePath,
                        explicitCliPath,
                        ffiEnvironment,
                        ffiArgs,
                        _logger);
                    _ffiHost = ffiHost;
                    await ffiHost.StartAsync(ct);
                    connection = await ConnectToServerAsync(null, null, null, null, ct, ffiHost);
                }
                else if (_connection is UriRuntimeConnection)
                {
                    // External runtime
                    _actualPort = _optionsPort;
                    connection = await ConnectToServerAsync(null, _optionsHost, _optionsPort, null, ct);
                }

View on GitHub (pinned to cd8cf15dc3)