github/copilot-sdk · error · ValueError

connection_token must be a non-empty string

Error message

connection_token must be a non-empty string

What it means

A UriRuntimeConnection with a connection_token present but an empty string is invalid: the token authenticates the URI-based runtime connection, and an empty value would be rejected downstream. The constructor raises ValueError immediately.

Solutions

1. Provide a non-empty connection_token string
2. Set connection_token to None (omit it) if no token is needed
3. Guard config loading so empty strings become None

Example fix

// before
conn = UriRuntimeConnection(url="http://localhost:8080", connection_token=os.environ.get("TOKEN", ""))
// after
token = os.environ.get("TOKEN") or None
conn = UriRuntimeConnection(url="http://localhost:8080", connection_token=token)

token = cfg.get("connection_token")
if token == "":
    raise ValueError("connection_token must not be empty; omit it or provide a value")
conn = UriRuntimeConnection(url=url, connection_token=token)

def valid_token(tok: str | None) -> bool:
    return tok is None or len(tok) > 0

try:
    client = CopilotClient(connection=conn)
except ValueError as e:
    if "connection_token must be a non-empty string" in str(e):
        conn = replace(conn, connection_token=None)
        client = CopilotClient(connection=conn)

When it happens

Trigger: Creating CopilotClient with a UriRuntimeConnection whose connection_token is set to "" (empty string), e.g. from an unset config value that defaults to empty rather than None.

Common situations: Config files with connection_token= left blank; reading the token via os.environ.get() returning empty string after an env var was set to nothing; stripping a placeholder during templating.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• agent_id must be a string
• builtin_plugin_directories must contain only absolute paths
• invalid entry '*': there is no bare wildcard. Use…
• invalid tool name: must not be empty
• invalid tool name : tool names must match…

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

Appendix: source

Thrown at python/copilot/client.py:1706

            is_uri_connection=isinstance(connection, UriRuntimeConnection),
        )

        self._options: _CopilotClientOptions = options
        self._connection: RuntimeConnection = connection
        self._on_list_models = options.on_list_models
        self._on_github_telemetry = options.on_github_telemetry

        # Resolve connection-mode-specific state.
        self._actual_host: str = "localhost"
        self._is_external_server: bool = isinstance(connection, UriRuntimeConnection)
        self._cli_path_source: str | None = None
        self._ffi_host: FfiRuntimeHost | None = None
        self._inprocess_runtime_path: str | None = None
        self._inprocess_cli_entrypoint: str | None = None

        if isinstance(connection, UriRuntimeConnection):
            if connection.connection_token is not None and len(connection.connection_token) == 0:
                raise ValueError("connection_token must be a non-empty string")
            self._actual_host, actual_port = self._parse_cli_url(connection.url)
            self._runtime_port: int | None = actual_port
            self._effective_connection_token: str | None = connection.connection_token
        elif isinstance(connection, InProcessRuntimeConnection):
            # In-process (FFI): no child process and no per-connection token.
            self._runtime_port = None
            self._effective_connection_token = None
            self._inprocess_runtime_path = self._resolve_inprocess_runtime()
            if options.use_logged_in_user is None:
                options.use_logged_in_user = not bool(options.github_token)
        else:
            assert isinstance(connection, ChildProcessRuntimeConnection)
            self._runtime_port = None

            if isinstance(connection, TcpRuntimeConnection):
                if (
                    connection.connection_token is not None
                    and len(connection.connection_token) == 0

View on GitHub (pinned to cd8cf15dc3)