github/copilot-sdk · error

Invalid port in cliUrl

Error message

Invalid port in cliUrl: ${url}

What it means

parseCliUrl extracted a port from the bracketed IPv6 form but parseInt produced NaN or a value outside 1-65535. The cliUrl string's port segment is syntactically numeric but semantically not a usable TCP port.

Solutions

1. Use a port in the range 1-65535, e.g. '[::1]:8080'
2. Check for leading zeros, embedded whitespace, or copy-paste artifacts like colons duplicated in the port segment
3. If the port comes from configuration, validate it before constructing the cliUrl string

When it happens

Trigger: Thrown at nodejs/src/client.ts:775 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at nodejs/src/client.ts:775

        const cleanUrl = url.replace(/^https?:\/\//, "");

        // Check if it's just a port number
        if (/^\d+$/.test(cleanUrl)) {
            return { host: "localhost", port: parseInt(cleanUrl, 10) };
        }

        // Handle the canonical bracketed IPv6 host:port form without changing
        // the existing parser behavior for other inputs.
        const ipv6Match = cleanUrl.match(/^\[([^\]]+)\]:(\d+)$/);
        if (ipv6Match) {
            const host = ipv6Match[1];
            if (!isIPv6(host)) {
                throw new Error(`Invalid cliUrl format: ${url}`);
            }

            const port = parseInt(ipv6Match[2], 10);
            if (isNaN(port) || port <= 0 || port > 65535) {
                throw new Error(`Invalid port in cliUrl: ${url}`);
            }
            return { host, port };
        }

        // Parse host:port format
        const parts = cleanUrl.split(":");
        if (parts.length !== 2) {
            throw new Error(
                `Invalid cliUrl format: ${url}. Expected "host:port", "[ipv6]:port", "http://host:port", or "port"`
            );
        }

        const host = parts[0] || "localhost";
        const port = parseInt(parts[1], 10);

        if (isNaN(port) || port <= 0 || port > 65535) {
            throw new Error(`Invalid port in cliUrl: ${url}`);
        }

View on GitHub (pinned to cd8cf15dc3)