BerriAI/litellm · error · ValueError

Error from qdrant checking if /collections exist {collection

Error message

Error from qdrant checking if /collections exist {collection_exists.text}

What it means

During construction the cache makes a synchronous HTTP GET to {qdrant_api_base}/collections/{collection_name}/exists; if the response status is not 200 it raises ValueError embedding the response body. Root causes range from auth failure (401/403), wrong URL, non-existent collection with permission errors, to a non-Qdrant server answering at that URL.

Source

Thrown at litellm/caching/qdrant_semantic_cache.py:96

            raise ValueError("Qdrant url must be provided")

        self.qdrant_api_base = qdrant_api_base
        self.qdrant_api_key = qdrant_api_key
        print_verbose(f"qdrant semantic-cache qdrant_api_base: {self.qdrant_api_base}")

        self.headers = headers

        self.sync_client = _get_httpx_client()
        self.async_client = get_async_httpx_client(llm_provider=httpxSpecialProvider.Caching)

        if quantization_config is None:
            print_verbose("Quantization config is not provided. Default binary quantization will be used.")
        collection_exists: Final = self.sync_client.get(
            url=f"{self.qdrant_api_base}/collections/{self.collection_name}/exists",
            headers=self.headers,
        )
        if collection_exists.status_code != 200:
            raise ValueError(f"Error from qdrant checking if /collections exist {collection_exists.text}")

        if collection_exists.json()["result"]["exists"]:
            collection_details = self.sync_client.get(
                url=f"{self.qdrant_api_base}/collections/{self.collection_name}",
                headers=self.headers,
            )
            self.collection_info = collection_details.json()
            print_verbose(f"Collection already exists.\nCollection details:{self.collection_info}")
            self._ensure_cache_key_payload_index()
        else:
            quantization_params: dict[str, Any]
            if quantization_config is None or quantization_config == "binary":
                quantization_params = {
                    "binary": {
                        "always_ram": False,
                    }
                }
            elif quantization_config == "scalar":

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Read the embedded response text in the message — it names the actual HTTP problem (401 vs 404 vs 502)
2. Reproduce the call manually: curl -H 'api-key: $QDRANT_API_KEY' $QDRANT_URL/collections/<name>/exists and fix whatever it reports
3. Confirm the URL uses the REST port (default 6333 for self-hosted) and the api-key header is valid
4. If a proxy sits in front of Qdrant, allowlist the /collections/* paths

Example fix

# before
cache = QdrantSemanticCache(collection_name='c', similarity_threshold=0.8,
                           qdrant_api_base='https://xyz.cloud.qdrant.io:6334')  # gRPC port

# after
cache = QdrantSemanticCache(collection_name='c', similarity_threshold=0.8,
                           qdrant_api_base='https://xyz.cloud.qdrant.io:6333')  # REST port

import httpx

def qdrant_reachable(base: str, key: str | None, collection: str) -> bool:
    headers = {'Content-Type': 'application/json', **({'api-key': key} if key else {})}
    try:
        r = httpx.get(f'{base}/collections/{collection}/exists', headers=headers, timeout=5)
        return r.status_code == 200
    except httpx.HTTPError:
        return False

try:
    cache = QdrantSemanticCache(collection_name='c', similarity_threshold=0.8,
                               qdrant_api_base=base, qdrant_api_key=key)
except ValueError as e:
    # message embeds the Qdrant response body — log it for diagnosis
    logger.error('Qdrant cache init failed: %s', e)
    raise

When it happens

Trigger: QdrantSemanticCache construction with an invalid or expired qdrant_api_key (401), a qdrant_api_base pointing at a proxy/gateway that returns 4xx/5xx, a Qdrant Cloud instance on a paused/free tier, or a URL with a wrong port.

Common situations: Rotated or mistyped Qdrant API key; pointing at the Qdrant gRPC port (6334) instead of the REST port (6333); corporate proxy intercepting the request; Qdrant Cloud cluster paused or deleted.

Related errors

• OpenMeter logging error: {e.response.text}
• collection_name must be provided, passed None
• similarity_threshold must be provided, passed None
• Qdrant url must be provided
• Error while creating new collection

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/2462300341391360. Report an issue: GitHub.