{"record":{"id":"50548d89236d7d06","repo":"github/copilot-sdk","slug":"copilot-runtime-connection-open-failed-50548d","errorCode":null,"errorMessage":"copilot_runtime_connection_open failed.","messagePattern":"copilot_runtime_connection_open failed\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java","lineNumber":140,"sourceCode":"                    // Best effort\n                }\n                throw new IllegalStateException(\"FfiRuntimeHost was closed during startup.\");\n            }\n            serverId.set(hostHandle);\n\n            OutboundCallback callback = createOutboundCallback();\n            callbackRef = callback;\n            int connHandle = nativeBinding.connectionOpen(hostHandle, callback, Pointer.NULL, null, 0, null, 0, null,\n                    0);\n            if (connHandle == 0) {\n                try {\n                    nativeBinding.hostShutdown(hostHandle);\n                } catch (Throwable ignored) {\n                    // Best effort\n                }\n                serverId.set(0);\n                callbackRef = null;\n                throw new IllegalStateException(\"copilot_runtime_connection_open failed.\");\n            }\n            connectionId.set(connHandle);\n            LOG.fine(() -> \"Started FFI runtime host. Library=\" + libraryPath + \", serverId=\" + hostHandle\n                    + \", connectionId=\" + connHandle);\n        } finally {\n            operationLock.unlock();\n        }\n    }\n\n    public InputStream getReceiveStream() {\n        return receiveStream;\n    }\n\n    public OutputStream getSendStream() {\n        return sendStream;\n    }\n\n    @Override","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java#L122-L158","documentation":"After the host handle was obtained, copilot_runtime_connection_open failed to open the outbound callback connection. The library cleans up (hostShutdown, resets serverId, clears callbackRef) and throws so no half-open state remains.","triggerScenarios":"Native connectionOpen returns 0/invalid handle: callback trampoline registration failure, host already unhealthy, invalid NULL parameters rejected natively, or native out-of-memory.","commonSituations":"Native runtime crashed or is an incompatible version whose connection_open signature/behavior differs; resource exhaustion in the embedded runtime.","solutions":["Verify the native runtime version matches the Java SDK.","Re-check that hostStart succeeded and the host is healthy (serverId != 0).","Reproduce with FINE logging and run the runtime standalone to isolate the native failure.","Retry with a fresh FfiRuntimeHost after cleanup — start() leaves a consistent closed-ish state."],"exampleFix":"// before\ntry { host.start(e, o); } catch (IllegalStateException ex) { /* half-cleaned */ }\n// after\ntry { host.start(e, o); } catch (IllegalStateException ex) {\n    host.close();\n    host = new FfiRuntimeHost(libPath); host.start(e, o);\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { host.start(e, o); } catch (IllegalStateException ex) { host.close(); host = new FfiRuntimeHost(libPath); retryStartWithBackoff(); }","preventionTips":["Keep native runtime and Java SDK versions in sync","Monitor native library health (host handle validity) before opening connections","Retry with a fresh host instance; never reuse a failed host"],"tags":["java","ffi","native","connection"],"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"}