{"record":{"id":"9c4aa2584ebcc5fc","repo":"github/copilot-sdk","slug":"copilot-runtime-host-start-failed-library-this","errorCode":null,"errorMessage":"copilot_runtime_host_start failed (library '${this.libraryPath}').","messagePattern":"copilot_runtime_host_start failed \\(library '(.+?)'\\)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"nodejs/src/ffiRuntimeHost.ts","lineNumber":208,"sourceCode":"        // host_start constructs the native engine synchronously; run it as an async FFI\n        // call so the Node event loop isn't blocked.\n        this.serverId = await new Promise<number>((resolvePromise, rejectPromise) => {\n            this.lib.hostStart.async(\n                argvJson,\n                argvJson.length,\n                envJson,\n                envJson ? envJson.length : 0,\n                (error: Error | null, result: number) => {\n                    if (error) {\n                        rejectPromise(error);\n                    } else {\n                        resolvePromise(result);\n                    }\n                }\n            );\n        });\n        if (!this.serverId) {\n            throw new Error(`copilot_runtime_host_start failed (library '${this.libraryPath}').`);\n        }\n\n        this.outboundCallback = koffi.register(\n            (_userData: unknown, bytesPtr: unknown, bytesLen: number | bigint) =>\n                this.feedInbound(bytesPtr, bytesLen),\n            this.lib.outboundCallbackType\n        );\n\n        this.connectionId = this.lib.connectionOpen(\n            this.serverId,\n            this.outboundCallback,\n            null,\n            null,\n            0,\n            null,\n            0,\n            null,\n            0","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/ffiRuntimeHost.ts#L190-L226","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst host = FfiRuntimeHost.create('/stale/libruntime.so', cliPath, env, args);\nawait host.start(); // throws: host_start failed\n// after\n// rebuild: cargo build --release, then point at the fresh artifact\nconst host = FfiRuntimeHost.create('/fresh/target/release/libruntime.so', cliPath, env, args);\nawait host.start();","handlingStrategy":"try-catch","validationCode":"// check version compatibility before start\nif (runtimeLibVersion !== expectedAbiVersion) throw new Error('Rebuild native library: ABI mismatch');","typeGuard":null,"tryCatchPattern":"try {\n  await host.start();\n} catch (e) {\n  if (String(e.message).includes('copilot_runtime_host_start failed')) {\n    console.error('Native host failed to start; rebuild/verify the cdylib and check env/args');\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["ffi","native-library","startup","runtime"],"backgroundTag":"module-init-failed","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}