{"record":{"id":"db3ff6124290b635","repo":"github/copilot-sdk","slug":"copilot-runtime-connection-open-failed","errorCode":null,"errorMessage":"copilot_runtime_connection_open failed.","messagePattern":"copilot_runtime_connection_open failed\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"nodejs/src/ffiRuntimeHost.ts","lineNumber":232,"sourceCode":"            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\n        );\n        if (!this.connectionId) {\n            this.unregisterCallback();\n            this.lib.hostShutdown(this.serverId);\n            this.serverId = 0;\n            throw new Error(\"copilot_runtime_connection_open failed.\");\n        }\n\n        // The in-process transport has no socket/pipe handle to keep the Node event loop\n        // alive while the SDK is idle awaiting a server→client frame. koffi delivers the\n        // outbound callback on the loop but does not reference it, so hold one referenced\n        // timer for the lifetime of the connection.\n        this.keepAliveTimer = setInterval(() => {}, KEEP_ALIVE_INTERVAL_MS);\n    }\n\n    private writeFrame(frame: Buffer): void {\n        if (this.disposed || !this.connectionId) {\n            throw new Error(\"The in-process runtime connection is closed.\");\n        }\n        const ok = this.lib.connectionWrite(this.connectionId, frame, frame.length);\n        if (!ok) {\n            throw new Error(\"Failed to write a frame to the in-process runtime connection.\");\n        }\n    }","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/ffiRuntimeHost.ts#L214-L250","documentation":"start() opens the client connection via copilot_runtime_connection_open after the host server starts. If the returned connectionId is falsy, it throws this error after cleaning up: it unregisters the outbound callback, shuts down the server, and resets serverId, leaving no partially initialized state.","triggerScenarios":"Calling start() when the native connection_open call fails — e.g. the host server started but could not open the in-process connection, native-side connection limits or configuration errors, or an ABI/version mismatch affecting the connection handshake.","commonSituations":"Mismatched native library version with different connection semantics; invalid host/CLI configuration that the connection setup rejects; resource exhaustion or native-side state preventing connection creation.","solutions":["Rebuild/align the native library version with the JS SDK so the connection ABI matches.","Validate the environment, CLI entrypoint, and args passed to create; fix invalid host configuration.","Check native-side logs for the underlying connection_open failure cause.","Retry in a fresh process after cleanup to rule out residual native state."],"exampleFix":"// before\nconst host = FfiRuntimeHost.create(libPath, undefined, env, args);\nawait host.start(); // throws: connection_open failed\n// after\nconst host = FfiRuntimeHost.create(libPath, resolve('./cli-entrypoint'), env, args);\nawait host.start(); // valid config lets connection_open succeed","handlingStrategy":"retry","validationCode":"// validate config the host will use before start\nif (!cliEntrypoint || !existsSync(resolve(cliEntrypoint))) throw new Error('Valid CLI entrypoint required for connection open');","typeGuard":null,"tryCatchPattern":"try {\n  await host.start();\n} catch (e) {\n  if (String(e.message).includes('copilot_runtime_connection_open failed')) {\n    // start() already cleaned up server/callbacks; safe to retry with fixed config\n    host = await recreateHostWithFixedConfig();\n    await host.start();\n  } else throw e;\n}","preventionTips":["Align native library version with the JS SDK before starting","Pass a valid CLI entrypoint and environment to create","Capture native logs to diagnose connection_open failures","Retry start in a fresh process after a failure to avoid residual native state"],"tags":["ffi","connection","native-library","startup"],"backgroundTag":"connection-refused","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"}