github/copilot-sdk · error · RuntimeError

{process exit error from _get_process_exit_error()}

Error message

{process exit error from _get_process_exit_error()}

What it means

During start(), if an exception occurs while waiting for the CLI process and the process has already exited (non-None return code), the library re-raises RuntimeError with the message produced by `_get_process_exit_error()`, which describes the process's exit code and captured stderr. This turns a generic startup failure into a diagnostic about why the CLI subprocess died.

Solutions

  1. Read the message: it includes the CLI exit code and stderr output — fix the underlying process error it names.
  2. Verify the installed Copilot CLI version is compatible with this client library.
  3. Run the CLI command manually with the same arguments to reproduce and see the error directly.
  4. Check file permissions and PATH resolution for the CLI binary.

Example fix

// before
await client.start()  # RuntimeError with process exit details
// after
try:
    await client.start()
except RuntimeError as e:
    print(f"CLI failed to start: {e}")  # shows exit code + stderr
    raise
Defensive patterns

Strategy: try-catch

Validate before calling

proc = await asyncio.create_subprocess_exec(cli_path, ...)
await asyncio.sleep(0.2)
if proc.returncode is not None:
    raise RuntimeError(f"CLI exits immediately with code {proc.returncode}")

Try / catch

try:
    await client.start()
except RuntimeError as e:
    # message includes CLI exit code and stderr from _get_process_exit_error()
    logger.error("CLI process died during startup: %s", e)
    raise

Prevention

When it happens

Trigger: The Copilot CLI process terminates during start() — bad CLI arguments, missing/unreadable binary, crash on launch, port conflicts — while the client is waiting for it to become ready.

Common situations: Outdated or incompatible CLI version; invalid flags passed through to the CLI; environment missing (e.g. no auth/telemetry config the CLI requires); the CLI binary failing immediately on an unsupported platform.

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

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

Appendix: source

Thrown at python/copilot/client.py:2031

            self._state = "error"
            log_timing(
                logger,
                logging.WARNING,
                "CopilotClient.start failed",
                start_time,
                exc_info=True,
            )
            # Check if process exited and capture any remaining stderr
            process = self._cli_process if self._cli_process is not None else self._process
            if process and hasattr(process, "poll"):
                if isinstance(e, BrokenPipeError) and process.poll() is None:
                    try:
                        await asyncio.to_thread(process.wait, timeout=1.0)
                    except subprocess.TimeoutExpired:
                        pass
                return_code = process.poll()
                if return_code is not None and self._client:
                    raise RuntimeError(self._client._get_process_exit_error()) from e
            raise

    async def stop(self) -> None:
        """
        Stop the CLI server and close all active sessions.

        This method performs graceful cleanup:
        1. Closes all active sessions (releases in-memory resources)
        2. Requests runtime shutdown for SDK-owned CLI processes
        3. Closes the JSON-RPC connection
        4. Terminates the CLI server process (if spawned by this client)

        Note: session data on disk is preserved, so sessions can be resumed
        later. To permanently remove session data before stopping, call
        :meth:`delete_session` for each session first.

        Raises:
            ExceptionGroup[StopError]: If any errors occurred during cleanup.

View on GitHub (pinned to cd8cf15dc3)