{"record":{"id":"ee690c7b94d9cade","repo":"github/copilot-sdk","slug":"failed-to-write-a-frame-to-the-in-process-runtime","errorCode":null,"errorMessage":"Failed to write a frame to the in-process runtime connection.","messagePattern":"Failed to write a frame to the in-process runtime connection\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/ffiRuntimeHost.ts","lineNumber":248,"sourceCode":"            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    }\n\n    /**\n     * Native outbound (server→client) callback. koffi delivers it on the JS event loop\n     * via a threadsafe function, so the frame is decoded and written straight to\n     * {@link receiveStream}. The native pointer is only valid for this call, so the\n     * bytes are copied out before returning.\n     */\n    private feedInbound(bytesPtr: unknown, bytesLen: number | bigint): void {\n        // An exception thrown across the native→JS (Node-API) boundary cannot propagate\n        // and would surface only as a DEP0168 \"uncaught Node-API callback exception\"\n        // warning, so catch and log it here instead of letting it escape.\n        try {\n            // A native outbound callback can still be delivered on the event loop after\n            // dispose() has ended receiveStream; writing then would throw\n            // ERR_STREAM_WRITE_AFTER_END. Drop late frames instead — the connection is\n            // gone and nothing is reading them.","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/ffiRuntimeHost.ts#L230-L266","documentation":"The native connectionWrite call returned false, meaning the FFI layer could not deliver the frame buffer to the in-process runtime. Unlike error 80 the connection is nominally open, but the underlying write failed — typically because the runtime process/pipe is dead or backpressured beyond recovery. Thrown from writeFrame during the constructor's handshake write.","triggerScenarios":"this.lib.connectionWrite(connectionId, frame, length) returns false for the initial handshake frame: the native runtime died at startup, the connection id became invalid, or the native buffer write failed.","commonSituations":"Corrupt or mismatched runtime.node binary, runtime crash immediately after launch, OOM-killed runtime process, platform-native binary version mismatch with the SDK.","solutions":["Reinstall the SDK so the correct platform runtime.node is present (see runtime bundle validation errors).","Check the runtime process logs/stderr for a crash right before the write failure.","Retry session creation — a transient runtime startup failure can produce a one-off write failure.","Confirm the runtime bundle version matches the SDK version (mixed installs cause protocol/ABI mismatch)."],"exampleFix":"// before\nconst { runtimePath } = ensureRuntimeBundle({});\nconst host = new FfiRuntimeHost(loadLib(runtimePath)); // runtime node from an old install\n\n// after\n// reinstall @github/copilot-sdk and its platform package so versions match\nnpm install @github/copilot-sdk","handlingStrategy":"retry","validationCode":"if (!existsSync(runtimePath)) throw new Error('runtime binary missing before connect');","typeGuard":null,"tryCatchPattern":"try {\n  host = new FfiRuntimeHost(lib);\n} catch (e) {\n  if (e.message.includes('Failed to write a frame')) {\n    // transient native failure: rebuild lib+host with backoff\n    await sleep(RETRY_MS);\n    host = createHost();\n  } else throw e;\n}","preventionTips":["Keep SDK and platform runtime package versions in lockstep.","Verify runtime.node integrity after install (non-zero size).","Monitor runtime process health/stderr for early crashes."],"tags":["ffi","native-write","runtime-crash","nodejs"],"backgroundTag":"broken-pipe","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"}