github/copilot-sdk · critical · InvalidOperationException

copilot_runtime_host_start failed

Error message

copilot_runtime_host_start failed (library '{_libraryPath}').

What it means

FfiRuntimeHost.StartAsync calls the native copilot_runtime_host_start entrypoint via P/Invoke. A return value of 0 means the native runtime failed to start its host, so this InvalidOperationException is thrown reporting which library was used, after which no connection can be opened.

Solutions

Check the native runtime's stderr/logs for the underlying startup failure cause
Verify the native library version matches the managed package version
Confirm cliEntrypoint and args are valid and reachable, and env vars are correct
Test the library standalone (e.g. ldd / otool) to rule out missing native dependencies

Example fix

// before
var host = FfiRuntimeHost.Create(libPath, cliEntrypoint: null, env, args, logger);
await host.StartAsync(); // copilot_runtime_host_start failed
// after
var host = FfiRuntimeHost.Create(libPath, cliEntrypoint: "/usr/local/bin/copilot-cli", env, args, logger);
try { await host.StartAsync(); }
catch (InvalidOperationException ex) { logger.LogError(ex, "FFI host start failed"); throw; }

Defensive patterns

Strategy: try-catch

Validate before calling

if (!File.Exists(libPath)) throw new FileNotFoundException(libPath);
// optionally check native deps: ldd libcopilot_runtime.so (exit code 0)

Try / catch

try { await host.StartAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("copilot_runtime_host_start failed")) { /* log, check native logs/versions, retry with corrected config */ }

Prevention

Keep native library and managed wrapper versions in sync
Capture native stderr/logs during startup for the root cause
Validate cliEntrypoint and env config before StartAsync
Smoke-test the native library on the target platform in CI

When it happens

Trigger: NativeHostStart returns 0 — the native library loaded but host initialization failed: invalid argv/env JSON, missing CLI entrypoint, incompatible runtime library version, or the native host failed its own startup (port/socket, permissions, corrupt install).

Common situations: Mismatched versions of the managed wrapper and native runtime; cliEntrypoint path wrong so the runtime can't bootstrap; bad environment variables passed through; library built for a different platform and returning failure.

Related errors

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

Appendix: source

Thrown at dotnet/src/FfiRuntimeHost.cs:115

        if (OperatingSystem.IsMacOS()) return "libcopilot_runtime.dylib";
        return "libcopilot_runtime.so";
    }

    /// <summary>
    /// Starts the in-process Rust runtime and opens the FFI JSON-RPC connection.
    /// </summary>
    public async Task StartAsync(CancellationToken cancellationToken)
    {
        // Keep synchronous native startup off the caller's async context.
        await Task.Run(() =>
        {
            var argvJson = BuildArgvJson(_cliEntrypoint, _args);
            var envJson = BuildEnvJson(_environment);

            _serverId = NativeHostStart(argvJson, envJson);
            if (_serverId == 0)
            {
                throw new InvalidOperationException(
                    $"copilot_runtime_host_start failed (library '{_libraryPath}').");
            }

            _connectionId = NativeOpenConnection(_serverId);
            if (_connectionId == 0)
            {
                DisposeNativeCallback();
                NativeHostShutdown(_serverId);
                _serverId = 0;
                throw new InvalidOperationException("copilot_runtime_connection_open failed.");
            }

            _sendStream = new CallbackSendStream(SendFrame);
        }, cancellationToken).ConfigureAwait(false);

        if (_logger.IsEnabled(LogLevel.Debug))
        {
            _logger.LogDebug(

View on GitHub (pinned to cd8cf15dc3)