github/copilot-sdk · critical · IllegalStateException

copilot_runtime_connection_open failed.

Error message

copilot_runtime_connection_open failed.

What it means

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.

Solutions

1. Verify the native runtime version matches the Java SDK.
2. Re-check that hostStart succeeded and the host is healthy (serverId != 0).
3. Reproduce with FINE logging and run the runtime standalone to isolate the native failure.
4. Retry with a fresh FfiRuntimeHost after cleanup — start() leaves a consistent closed-ish state.

Example fix

// before
try { host.start(e, o); } catch (IllegalStateException ex) { /* half-cleaned */ }
// after
try { host.start(e, o); } catch (IllegalStateException ex) {
    host.close();
    host = new FfiRuntimeHost(libPath); host.start(e, o);
}

try { host.start(e, o); } catch (IllegalStateException ex) { host.close(); host = new FfiRuntimeHost(libPath); retryStartWithBackoff(); }

When it happens

Trigger: Native connectionOpen returns 0/invalid handle: callback trampoline registration failure, host already unhealthy, invalid NULL parameters rejected natively, or native out-of-memory.

Common situations: Native runtime crashed or is an incompatible version whose connection_open signature/behavior differs; resource exhaustion in the embedded runtime.

Related errors

• copilot_runtime_host_start failed (library '').
• copilot_runtime_connection_open failed.
• copilot_runtime_connection_open failed.
• Cannot connect: no process for stdio and no host:port for…
• The in-process runtime connection is closed.

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java:140

                    // Best effort
                }
                throw new IllegalStateException("FfiRuntimeHost was closed during startup.");
            }
            serverId.set(hostHandle);

            OutboundCallback callback = createOutboundCallback();
            callbackRef = callback;
            int connHandle = nativeBinding.connectionOpen(hostHandle, callback, Pointer.NULL, null, 0, null, 0, null,
                    0);
            if (connHandle == 0) {
                try {
                    nativeBinding.hostShutdown(hostHandle);
                } catch (Throwable ignored) {
                    // Best effort
                }
                serverId.set(0);
                callbackRef = null;
                throw new IllegalStateException("copilot_runtime_connection_open failed.");
            }
            connectionId.set(connHandle);
            LOG.fine(() -> "Started FFI runtime host. Library=" + libraryPath + ", serverId=" + hostHandle
                    + ", connectionId=" + connHandle);
        } finally {
            operationLock.unlock();
        }
    }

    public InputStream getReceiveStream() {
        return receiveStream;
    }

    public OutputStream getSendStream() {
        return sendStream;
    }

    @Override

View on GitHub (pinned to cd8cf15dc3)