github/copilot-sdk · error · IOException

Timeout waiting for CLI to announce port

Error message

Timeout waiting for CLI to announce port

What it means

waitForPortAnnouncement waits until a deadline for the CLI to print its TCP port on stdout. If the deadline expires without a port announcement, the manager forcibly destroys the process and throws IOException. The CLI either never announces a port or takes longer than the timeout.

Solutions

1. Increase the CLI startup timeout if startup is merely slow on your machine/CI.
2. Run the CLI manually to confirm it starts and announces a port in the expected format.
3. Update the SDK and CLI together so the port-announcement format matches.
4. Inspect stderr output captured by the manager for hints about what the CLI is waiting on.

Example fix

// before
CopilotClient client = new CopilotClient(options); // default short timeout
// after
options.setTimeout(Duration.ofSeconds(120)); // allow slow CLI startup
CopilotClient client = new CopilotClient(options);

long started = System.currentTimeMillis();
// ensure your configured startup timeout exceeds worst-case CLI boot time on target machines

try {
  client = manager.startCliServer();
} catch (IOException e) {
  if (e.getMessage().contains("Timeout waiting for CLI")) {
    // retry once, or increase startup timeout
  } else throw e;
}

When it happens

Trigger: startCliServer's stdout reader loops until the deadline while no line matches the port pattern — slow CLI startup (cold cache, slow machine), a CLI version that doesn't print the port, or startup blocked waiting for input/auth.

Common situations: Very slow CI machines exceeding the startup timeout; CLI hanging on an interactive prompt; version mismatch where the CLI output format no longer matches the expected port pattern; network/auth stalls during CLI boot.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• CLI process exited unexpectedly.
• Cannot connect: no process for stdio and no host:port for…
• CLI process exited unexpectedly.
• copilot_runtime_host_start failed (library '').
• Timeout waiting for CLI server to start

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/CliServerManager.java:209

            Pattern portPattern = Pattern.compile("listening on port (\\d+)", Pattern.CASE_INSENSITIVE);
            long deadline = System.currentTimeMillis() + 30000;

            while (System.currentTimeMillis() < deadline) {
                String line = reader.readLine();
                if (line == null) {
                    awaitStderrReader();
                    String stderr = getStderrOutput();
                    throw new IOException(formatCliExitedMessage("CLI process exited unexpectedly.", stderr));
                }

                Matcher matcher = portPattern.matcher(line);
                if (matcher.find()) {
                    return Integer.parseInt(matcher.group(1));
                }
            }

            process.destroyForcibly();
            throw new IOException("Timeout waiting for CLI to announce port");
        }
    }

    String getStderrOutput() {
        synchronized (stderrBuffer) {
            return stderrBuffer.toString().trim();
        }
    }

    private void awaitStderrReader() {
        Thread t = this.stderrThread;
        if (t != null) {
            try {
                t.join(STDERR_READER_JOIN_TIMEOUT_MS);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        }

View on GitHub (pinned to cd8cf15dc3)