chroma-core/chroma · error · ValueError

Invalid URL. Seems that you are trying to pass URL as a host

Error message

Invalid URL. Seems that you are trying to pass URL as a host but without                   specifying the protocol. Please add http:// or https:// to the host.

What it means

Second host-validation branch: the host contains '/' but does not start with 'http', and urlparse() found no recognized scheme (e.g. "example.com/api" or "/server"). The message is literal — Chroma thinks you pasted a URL as a host and forgot the protocol.

Source

Thrown at chromadb/api/base_http_client.py:58

        max_keepalive_connections = self._settings.chroma_http_max_keepalive_connections
        if max_keepalive_connections is not None:
            limit_kwargs["max_keepalive_connections"] = max_keepalive_connections

        return httpx.Limits(**limit_kwargs)

    @property
    def http_limits(self) -> httpx.Limits:
        return self._http_limits

    @staticmethod
    def _validate_host(host: str) -> None:
        parsed = urlparse(host)
        if "/" in host and parsed.scheme not in {"http", "https"}:
            raise ValueError(
                "Invalid URL. " f"Unrecognized protocol - {parsed.scheme}."
            )
        if "/" in host and (not host.startswith("http")):
            raise ValueError(
                "Invalid URL. "
                "Seems that you are trying to pass URL as a host but without \
                  specifying the protocol. "
                "Please add http:// or https:// to the host."
            )

    @staticmethod
    def resolve_url(
        chroma_server_host: str,
        chroma_server_ssl_enabled: Optional[bool] = False,
        default_api_path: Optional[str] = "",
        chroma_server_http_port: Optional[int] = 8000,
    ) -> str:
        _skip_port = False
        _chroma_server_host = chroma_server_host
        BaseHTTPClient._validate_host(_chroma_server_host)
        if _chroma_server_host.startswith("http"):
            logger.debug("Skipping port as the user is passing a full URL")

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Add the protocol if you mean a URL: host="https://chroma.example.com" (with ssl settings as needed).
2. Or strip the path and pass just the hostname, letting the port/path arguments carry the rest.
3. Set CHROMA_SERVER_HOST to a bare hostname instead of a URL.

Example fix

# before
client = HttpClient(host="chroma.internal/api")  # ValueError: add http:// or https://

# after
client = HttpClient(host="https://chroma.internal")

def needs_protocol(host: str) -> bool:
    return "/" in host and not host.startswith("http")

host = "chroma.internal/api"
if needs_protocol(host):
    host = "https://" + host.split("/")[0]  # or fix at the config source

try:
    client = chromadb.HttpClient(host=host)
except ValueError:
    # message asks to add http:// or https:// — fix the host string
    host = f"https://{host}" if "/" in host else host
    client = chromadb.HttpClient(host=host)

When it happens

Trigger: HttpClient(host="chroma.example.com/api"); host="/api/v2"; any host-with-path string that has no scheme prefix. (Strings like "localhost:8000/api" do not reach this branch — they fail the earlier 'Unrecognized protocol' check instead.)

Common situations: Copying the path-qualified URL from a reverse-proxied deployment into host; config files ported from tools that expect host+path in one field.

Related errors

• Invalid URL. Unrecognized protocol - {parsed.scheme}.
• Embedding function provided when already defined in the coll
• not a valid space: {space_value}
• Cannot update embedding function: incompatible types ({exist
• Multiple embedding functions provided. Please provide only o

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/8c900bb243d48d33. Report an issue: GitHub.