github/copilot-sdk · error · ValueError

Invalid cli_url format

Error message

Invalid cli_url format: {url}

What it means

This ValueError is raised when the host portion of a bracketed IPv6 cli_url is not a valid IPv6 address. The parser matches `[#]...` and validates the host with `ipaddress.IPv6Address(host)`; a ValueError there is re-raised as this error. It ensures malformed IPv6 literals fail fast with a clear message.

Solutions

1. Use a valid bracketed IPv6 URL, e.g. cli_url='http://[::1]:4242'.
2. Or use an IPv4/hostname form like 'http://localhost:4242'.
3. Validate the URL with `ipaddress.IPv6Address()` before passing it in.

Example fix

// before
client = CopilotClient(cli_url="http://[zz::1]:4242")
// after
client = CopilotClient(cli_url="http://[::1]:4242")

import ipaddress, re
m = re.match(r"^\[([^\]]+)\]", re.sub(r"^https?://", "", url))
if m:
    ipaddress.IPv6Address(m.group(1))  # raises before client construction

try:
    client = CopilotClient(cli_url=url)
except ValueError as e:
    if "Invalid cli_url format" in str(e):
        raise ConfigError(f"malformed cli_url: {url}") from e
    raise

When it happens

Trigger: Passing cli_url like 'http://[zz::1]:4242', 'http://[abc]:8080', or 'http://[]:4242' — bracketed text that is not parseable as IPv6.

Common situations: Hand-edited config files with malformed IPv6 literals; missing the brackets and writing 'http://::1:4242' which the parser misreads; environment-specific URLs copy-pasted incorrectly.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Invalid port in cli_url
• Invalid URIConnection format
• Invalid entry '*': there is no bare wildcard. Use one or…
• Client is not connected. Call start() first.
• telemetry is not supported with…

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

Appendix: source

Thrown at python/copilot/client.py:1871

            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]

        try:
            port = int(port_text)
        except ValueError as e:
            raise ValueError(f"Invalid port in cli_url: {url}") from e

        if port <= 0 or port > 65535:
            raise ValueError(f"Invalid port in cli_url: {url}")

        return (host, port)

View on GitHub (pinned to cd8cf15dc3)