copilot_runtime_host_start failed

Error message

copilot_runtime_host_start failed (library '${this.libraryPath}').

What it means

start() invokes the native copilot_runtime_host_start export; after the async start call resolves, if this.serverId is still falsy the start failed and this error is thrown with the library path for diagnostics. It means the native runtime host could not be started, e.g. initialization inside the cdylib failed or returned a zero/invalid server id.

Solutions

Rebuild the native runtime library so it matches the JS bindings' expected ABI/version.
Check the environment and CLI entrypoint arguments passed to create/start.
Capture native-side logs/stderr to find the underlying host_start failure.
Verify the library file is the correct build for the current platform and not corrupted.

Example fix

// before
const host = FfiRuntimeHost.create('/stale/libruntime.so', cliPath, env, args);
await host.start(); // throws: host_start failed
// after
// rebuild: cargo build --release, then point at the fresh artifact
const host = FfiRuntimeHost.create('/fresh/target/release/libruntime.so', cliPath, env, args);
await host.start();

Defensive patterns

Strategy: try-catch

Validate before calling

// check version compatibility before start
if (runtimeLibVersion !== expectedAbiVersion) throw new Error('Rebuild native library: ABI mismatch');

Try / catch

try {
  await host.start();
} catch (e) {
  if (String(e.message).includes('copilot_runtime_host_start failed')) {
    console.error('Native host failed to start; rebuild/verify the cdylib and check env/args');
  }
  throw e;
}

Prevention

Keep the native library and JS SDK versions in lockstep
Log native stderr/stdout to diagnose host_start failures
Validate environment variables and CLI entrypoint before start
Test host startup in CI on every native build

When it happens

Trigger: Calling start() when the native copilot_runtime_host_start call fails or returns no server id — e.g. a broken/mismatched library version whose ABI differs, native-side initialization errors (bad environment/args), or the callback registration contract not being honored.

Common situations: Stale build of the native library that no longer matches the JS ABI expectations; missing required environment variables or CLI entrypoint passed incorrectly; corrupted or incompatible native binary for the platform.

Related errors

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

Appendix: source

Thrown at nodejs/src/ffiRuntimeHost.ts:208

        // host_start constructs the native engine synchronously; run it as an async FFI
        // call so the Node event loop isn't blocked.
        this.serverId = await new Promise<number>((resolvePromise, rejectPromise) => {
            this.lib.hostStart.async(
                argvJson,
                argvJson.length,
                envJson,
                envJson ? envJson.length : 0,
                (error: Error | null, result: number) => {
                    if (error) {
                        rejectPromise(error);
                    } else {
                        resolvePromise(result);
                    }
                }
            );
        });
        if (!this.serverId) {
            throw new Error(`copilot_runtime_host_start failed (library '${this.libraryPath}').`);
        }

        this.outboundCallback = koffi.register(
            (_userData: unknown, bytesPtr: unknown, bytesLen: number | bigint) =>
                this.feedInbound(bytesPtr, bytesLen),
            this.lib.outboundCallbackType
        );

        this.connectionId = this.lib.connectionOpen(
            this.serverId,
            this.outboundCallback,
            null,
            null,
            0,
            null,
            0,
            null,
            0

View on GitHub (pinned to cd8cf15dc3)