{"record":{"id":"e343d82b22f1fb85","repo":"chroma-core/chroma","slug":"invalid-url-unrecognized-protocol-parsed-schem","errorCode":null,"errorMessage":"Invalid URL. Unrecognized protocol - {parsed.scheme}.","messagePattern":"Invalid URL\\. Unrecognized protocol - (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/base_http_client.py","lineNumber":54,"sourceCode":"        max_connections = self._settings.chroma_http_max_connections\n        if max_connections is not None:\n            limit_kwargs[\"max_connections\"] = max_connections\n\n        max_keepalive_connections = self._settings.chroma_http_max_keepalive_connections\n        if max_keepalive_connections is not None:\n            limit_kwargs[\"max_keepalive_connections\"] = max_keepalive_connections\n\n        return httpx.Limits(**limit_kwargs)\n\n    @property\n    def http_limits(self) -> httpx.Limits:\n        return self._http_limits\n\n    @staticmethod\n    def _validate_host(host: str) -> None:\n        parsed = urlparse(host)\n        if \"/\" in host and parsed.scheme not in {\"http\", \"https\"}:\n            raise ValueError(\n                \"Invalid URL. \" f\"Unrecognized protocol - {parsed.scheme}.\"\n            )\n        if \"/\" in host and (not host.startswith(\"http\")):\n            raise ValueError(\n                \"Invalid URL. \"\n                \"Seems that you are trying to pass URL as a host but without \\\n                  specifying the protocol. \"\n                \"Please add http:// or https:// to the host.\"\n            )\n\n    @staticmethod\n    def resolve_url(\n        chroma_server_host: str,\n        chroma_server_ssl_enabled: Optional[bool] = False,\n        default_api_path: Optional[str] = \"\",\n        chroma_server_http_port: Optional[int] = 8000,\n    ) -> str:\n        _skip_port = False","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/base_http_client.py#L36-L72","documentation":"Host validation in BaseHTTPClient.resolve_url(): the host string contains a '/' and urlparse() extracted a scheme that is not http or https. Chroma accepts either a bare hostname/IP or a full http(s):// URL; anything else with a slash is rejected. Notably, urlparse('localhost:8000/api') yields scheme 'localhost', so passing host:port/path as the host trips this exact branch with \"Unrecognized protocol - localhost\".","triggerScenarios":"HttpClient(host=\"localhost:8000/api/v2\") — the port belongs in the port argument; host=\"ftp://box\" or host=\"tcp://box\"; any scheme-prefixed string other than http/https.","commonSituations":"Pasting a URL copied from docs or a browser into the host parameter; migrating config from another SDK that takes a full DSN; putting the API path in the host.","solutions":["Pass a bare hostname and use the port argument: HttpClient(host=\"localhost\", port=8000).","If you intend to pass a full URL, prefix it with http:// or https:// (e.g. host=\"http://localhost:8000\").","Move any API path out of the host — the client builds the path itself."],"exampleFix":"# before\nclient = HttpClient(host=\"localhost:8000/api/v2\")  # ValueError: Unrecognized protocol - localhost\n\n# after\nclient = HttpClient(host=\"localhost\", port=8000)","handlingStrategy":"validation","validationCode":"from urllib.parse import urlparse\n\ndef valid_chroma_host(host: str) -> bool:\n    parsed = urlparse(host)\n    return \"/\" not in host or parsed.scheme in {\"http\", \"https\"}\n\nassert valid_chroma_host(\"localhost:8000/api\") is False  # would raise in the client\nassert valid_chroma_host(\"localhost\") is True","typeGuard":null,"tryCatchPattern":"try:\n    client = chromadb.HttpClient(host=host, port=port)\nexcept ValueError as e:  # raised from resolve_url host validation\n    raise ValueError(f\"Fix the host setting {host!r}: {e}\") from e","preventionTips":["Keep host to a bare hostname/IP; pass the port separately.","Lint config: reject host values containing '/' unless they start with http(s)://.","Use dedicated CHROMA_SERVER_HOST/CHROMA_SERVER_PORT variables rather than one URL string."],"tags":["chroma","url","configuration","input-validation","host"],"backgroundTag":"invalid-url-format","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}