What causes "Invalid port in cli_url: {url}" in github/copilot-sdk?

Use a valid port between 1 and 65535, e.g. cli_url='http://localhost:4242'.

github/copilot-sdk · error · ValueError

Invalid port in cli_url

Error message

Invalid port in cli_url: {url}

What it means

This ValueError comes from the cli_url parser when the URL is a bare port number (e.g. 'http://99999' or '99999'). After stripping the scheme, digits are interpreted as a port, and the code validates it must be in 1..65535. Ports outside that range cannot be bound, so the parser rejects them up front.

Solutions

Use a valid port between 1 and 65535, e.g. cli_url='http://localhost:4242'.
If the value should be a full host:port, supply it in that form instead of just a number.
Validate the port range in config loading before constructing the client.

Example fix

// before
client = CopilotClient(cli_url="http://70000")
// after
client = CopilotClient(cli_url="http://localhost:4242")

Defensive patterns

Strategy: validation

Validate before calling

def validate_cli_url(url: str) -> None:
    clean = re.sub(r"^https?://", "", url)
    if clean.isdigit() and not (1 <= int(clean) <= 65535):
        raise ValueError(f"port out of range: {url}")

Try / catch

try:
    client = CopilotClient(cli_url=url)
except ValueError as e:
    if "Invalid port" in str(e):
        raise ConfigError(f"cli_url port must be 1-65535: {url}") from e
    raise

Prevention

Validate ports against 1-65535 when loading config
Never use 0 or -1 as placeholder ports
Prefer full host:port URLs over bare port numbers

When it happens

Trigger: Passing `cli_url='http://0'`, `'http://70000'`, `'-1'`, or any numeric string outside 1-65535 to CopilotClient or the CLI URL option.

Common situations: See trigger scenarios.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at python/copilot/client.py:1861

        Supports formats: "host:port", "[ipv6]:port", "http://host:port",
        "https://host:port", or just "port".

        Args:
            url: The CLI URL to parse.

        Returns:
            A tuple of (host, port).

        Raises:
            ValueError: If the URL format is invalid or the port is out of range.
        """
        clean_url = re.sub(r"^https?://", "", url)

        # Check if it's just a port number
        if clean_url.isdigit():
            port = int(clean_url)
            if port <= 0 or port > 65535:
                raise ValueError(f"Invalid port in cli_url: {url}")
            return ("localhost", port)

        ipv6_match = re.match(r"^\[([^\]]+)\]:(.*)$", clean_url)
        if ipv6_match:
            host = ipv6_match.group(1)
            port_text = ipv6_match.group(2)
            try:
                ipaddress.IPv6Address(host)
            except ValueError as e:
                raise ValueError(f"Invalid cli_url format: {url}") from e
        else:
            # Parse host:port format
            parts = clean_url.split(":")
            if len(parts) != 2:
                raise ValueError(f"Invalid cli_url format: {url}")
            host = parts[0] if parts[0] else "localhost"
            port_text = parts[1]

View on GitHub (pinned to cd8cf15dc3)