{"record":{"id":"2970fa91389b90d0","repo":"BerriAI/litellm","slug":"qdrant-url-must-be-provided","errorCode":null,"errorMessage":"Qdrant url must be provided","messagePattern":"Qdrant url must be provided","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/caching/qdrant_semantic_cache.py","lineNumber":78,"sourceCode":"        self.vector_size = vector_size if vector_size is not None else QDRANT_VECTOR_SIZE\n        headers = {}\n\n        # check if defined as os.environ/ variable\n        if qdrant_api_base:\n            if isinstance(qdrant_api_base, str) and qdrant_api_base.startswith(\"os.environ/\"):\n                qdrant_api_base = get_secret_str(qdrant_api_base)\n        if qdrant_api_key:\n            if isinstance(qdrant_api_key, str) and qdrant_api_key.startswith(\"os.environ/\"):\n                qdrant_api_key = get_secret_str(qdrant_api_key)\n\n        qdrant_api_base = qdrant_api_base or os.getenv(\"QDRANT_URL\") or os.getenv(\"QDRANT_API_BASE\")\n        qdrant_api_key = qdrant_api_key or os.getenv(\"QDRANT_API_KEY\")\n        headers = {\"Content-Type\": \"application/json\"}\n        if qdrant_api_key:\n            headers[\"api-key\"] = qdrant_api_key\n\n        if qdrant_api_base is None:\n            raise ValueError(\"Qdrant url must be provided\")\n\n        self.qdrant_api_base = qdrant_api_base\n        self.qdrant_api_key = qdrant_api_key\n        print_verbose(f\"qdrant semantic-cache qdrant_api_base: {self.qdrant_api_base}\")\n\n        self.headers = headers\n\n        self.sync_client = _get_httpx_client()\n        self.async_client = get_async_httpx_client(llm_provider=httpxSpecialProvider.Caching)\n\n        if quantization_config is None:\n            print_verbose(\"Quantization config is not provided. Default binary quantization will be used.\")\n        collection_exists: Final = self.sync_client.get(\n            url=f\"{self.qdrant_api_base}/collections/{self.collection_name}/exists\",\n            headers=self.headers,\n        )\n        if collection_exists.status_code != 200:\n            raise ValueError(f\"Error from qdrant checking if /collections exist {collection_exists.text}\")","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/caching/qdrant_semantic_cache.py#L60-L96","documentation":"The Qdrant semantic cache needs the URL of a Qdrant server. The constructor resolves it from the qdrant_api_base argument, then the QDRANT_URL environment variable, then QDRANT_API_BASE; if all are empty it raises ValueError. This fails during construction, before the collection-existence check.","triggerScenarios":"Constructing QdrantSemanticCache without qdrant_api_base while neither QDRANT_URL nor QDRANT_API_BASE is set in the process environment (common in fresh deploy targets, CI, or containers where the env var was set in a different shell).","commonSituations":"Env var set locally but not in the deployment (Docker/Kubernetes env not injected); typo in the variable name (e.g. QDRANT_ENDPOINT); value stored only in a .env file that the running process never loaded.","solutions":["Pass qdrant_api_base explicitly, e.g. QdrantSemanticCache(..., qdrant_api_base='https://xyz.cloud.qdrant.io:6333')","Or export QDRANT_URL (or QDRANT_API_BASE) in the environment the process actually runs in: export QDRANT_URL=https://xyz.cloud.qdrant.io:6333","Verify with print(os.getenv('QDRANT_URL')) in the same process to rule out env-propagation issues"],"exampleFix":"# before\nQDRANT_API_BASE  # typo / unset\ncache = QdrantSemanticCache(collection_name='c', similarity_threshold=0.8)\n\n# after\ncache = QdrantSemanticCache(\n    collection_name='c',\n    similarity_threshold=0.8,\n    qdrant_api_base='https://xyz.cloud.qdrant.io:6333',\n    qdrant_api_key='your-key',\n)","handlingStrategy":"validation","validationCode":"import os\n\nqdrant_url = cfg.get('qdrant_api_base') or os.getenv('QDRANT_URL') or os.getenv('QDRANT_API_BASE')\nif not qdrant_url:\n    raise ValueError('Set qdrant_api_base or the QDRANT_URL env var before enabling qdrant semantic caching')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer explicit qdrant_api_base in config over implicit env lookup so failures are local","Add env-var presence checks to deployment readiness probes"],"tags":["qdrant","configuration","environment","semantic-cache"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}