{"record":{"id":"23c5d2b0517858ed","repo":"github/copilot-sdk","slug":"connection-token-must-be-a-non-empty-string","errorCode":null,"errorMessage":"connection_token must be a non-empty string","messagePattern":"connection_token must be a non-empty string","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":1706,"sourceCode":"            is_uri_connection=isinstance(connection, UriRuntimeConnection),\n        )\n\n        self._options: _CopilotClientOptions = options\n        self._connection: RuntimeConnection = connection\n        self._on_list_models = options.on_list_models\n        self._on_github_telemetry = options.on_github_telemetry\n\n        # Resolve connection-mode-specific state.\n        self._actual_host: str = \"localhost\"\n        self._is_external_server: bool = isinstance(connection, UriRuntimeConnection)\n        self._cli_path_source: str | None = None\n        self._ffi_host: FfiRuntimeHost | None = None\n        self._inprocess_runtime_path: str | None = None\n        self._inprocess_cli_entrypoint: str | None = None\n\n        if isinstance(connection, UriRuntimeConnection):\n            if connection.connection_token is not None and len(connection.connection_token) == 0:\n                raise ValueError(\"connection_token must be a non-empty string\")\n            self._actual_host, actual_port = self._parse_cli_url(connection.url)\n            self._runtime_port: int | None = actual_port\n            self._effective_connection_token: str | None = connection.connection_token\n        elif isinstance(connection, InProcessRuntimeConnection):\n            # In-process (FFI): no child process and no per-connection token.\n            self._runtime_port = None\n            self._effective_connection_token = None\n            self._inprocess_runtime_path = self._resolve_inprocess_runtime()\n            if options.use_logged_in_user is None:\n                options.use_logged_in_user = not bool(options.github_token)\n        else:\n            assert isinstance(connection, ChildProcessRuntimeConnection)\n            self._runtime_port = None\n\n            if isinstance(connection, TcpRuntimeConnection):\n                if (\n                    connection.connection_token is not None\n                    and len(connection.connection_token) == 0","sourceCodeStart":1688,"sourceCodeEnd":1724,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L1688-L1724","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide a non-empty connection_token string","Set connection_token to None (omit it) if no token is needed","Guard config loading so empty strings become None"],"exampleFix":"// before\nconn = UriRuntimeConnection(url=\"http://localhost:8080\", connection_token=os.environ.get(\"TOKEN\", \"\"))\n// after\ntoken = os.environ.get(\"TOKEN\") or None\nconn = UriRuntimeConnection(url=\"http://localhost:8080\", connection_token=token)","handlingStrategy":"validation","validationCode":"token = cfg.get(\"connection_token\")\nif token == \"\":\n    raise ValueError(\"connection_token must not be empty; omit it or provide a value\")\nconn = UriRuntimeConnection(url=url, connection_token=token)","typeGuard":"def valid_token(tok: str | None) -> bool:\n    return tok is None or len(tok) > 0","tryCatchPattern":"try:\n    client = CopilotClient(connection=conn)\nexcept ValueError as e:\n    if \"connection_token must be a non-empty string\" in str(e):\n        conn = replace(conn, connection_token=None)\n        client = CopilotClient(connection=conn)","preventionTips":["Convert empty strings from env/config to None before building connections","Coerce os.environ.get() results with 'or None'","Validate connection objects in a factory before use"],"tags":["python","validation","connection"],"backgroundTag":"empty-required-field","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}