github/copilot-sdk · error · RuntimeError

copilot_runtime_connection_open failed.

Error message

copilot_runtime_connection_open failed.

What it means

After host_start succeeds, start_blocking opens a connection with copilot_runtime_connection_open; a zero connection id means the connection could not be established. The library then shuts the host down again and raises this error.

Solutions

1. Retry start_blocking once after ensuring process resource limits (fds, memory) are sufficient.
2. Verify the runtime library version matches the Python client version (upgrade both together).
3. Check the host's stderr/native logs for the root cause of the connection failure.
4. Reinstall the runtime if the binary is suspected corrupt.

try:
    host.start_blocking()
except RuntimeError as e:
    if "connection_open failed" in str(e):
        host.dispose(); host = recreate_host(); host.start_blocking()

When it happens

Trigger: connection_open returning 0 during start_blocking — the native host is running but refused/failed to open the RPC connection (e.g. host failed internal init right after start, resource limits, or invalid connection parameters).

Common situations: Native host crashed immediately after start; out-of-memory or fd limits in the process; a runtime version whose connection protocol does not accept the parameters used.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• copilot_runtime_connection_open failed.
• copilot_runtime_connection_open failed.
• The in-process runtime connection is closed.
• Failed to write a frame to the in-process runtime…
• copilot_runtime_host_start failed (library '').

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

Appendix: source

Thrown at python/copilot/_ffi_runtime_host.py:443

            )

        self._outbound_callback = _OutboundCallback(self._on_outbound)
        self._connection_id = self._lib.connection_open(
            self._server_id,
            self._outbound_callback,
            None,
            None,
            0,
            None,
            0,
            None,
            0,
        )
        if not self._connection_id:
            self._outbound_callback = None
            self._lib.host_shutdown(self._server_id)
            self._server_id = 0
            raise RuntimeError("copilot_runtime_connection_open failed.")

    def _on_outbound(
        self,
        _user_data: int | None,
        bytes_ptr: ctypes._Pointer,
        bytes_len: int,
    ) -> None:
        """Native server → client callback (invoked on a foreign runtime thread).

        The native pointer is only valid for this call, so the bytes are copied
        out before returning. Exceptions must not cross the FFI boundary, so
        everything is caught and logged.
        """
        with self._callback_lock:
            if self._disposed:
                return
            self._active_callbacks += 1
        try:

View on GitHub (pinned to cd8cf15dc3)