{"record":{"id":"220fd52bd34a6dfa","repo":"stanford-oval/storm","slug":"error-occurs-when-connecting-to-the-server-e-220fd5","errorCode":null,"errorMessage":"Error occurs when connecting to the server: {e}","messagePattern":"Error occurs when connecting to the server: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"knowledge_storm/utils.py","lineNumber":127,"sourceCode":"\n        Args:\n            url (str): URL of the Qdrant server.\n            api_key (str): API key for the Qdrant server.\n        \"\"\"\n        if api_key is None:\n            if not os.getenv(\"QDRANT_API_KEY\"):\n                raise ValueError(\"Please provide an api key.\")\n            api_key = os.getenv(\"QDRANT_API_KEY\")\n        if url is None:\n            raise ValueError(\"Please provide a url for the Qdrant server.\")\n\n        try:\n            client = QdrantClient(url=url, api_key=api_key)\n            return QdrantVectorStoreManager._check_create_collection(\n                client=client, collection_name=collection_name, model=model\n            )\n        except Exception as e:\n            raise ValueError(f\"Error occurs when connecting to the server: {e}\")\n\n    @staticmethod\n    def _init_offline_vector_db(\n        vector_store_path: str, collection_name: str, model: \"HuggingFaceEmbeddings\"\n    ):\n        from qdrant_client import QdrantClient\n\n        \"\"\"Initialize the Qdrant client that is connected to an offline vector store with the given vector store folder path.\n\n        Args:\n            vector_store_path (str): Path to the vector store.\n        \"\"\"\n        if vector_store_path is None:\n            raise ValueError(\"Please provide a folder path.\")\n\n        try:\n            client = QdrantClient(path=vector_store_path)\n            return QdrantVectorStoreManager._check_create_collection(","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/stanford-oval/storm/blob/fb951af7744dab086e34962e9bc6fe878e145f83/knowledge_storm/utils.py#L109-L145","documentation":"Raised by QdrantVectorStoreManager._init_online_vector_db when QdrantClient(url, api_key) construction or the subsequent _check_create_collection call throws any exception — network/DNS failure, TLS error, 401 from a bad key, or an invalid URL. The original exception's message is interpolated into a generic ValueError, and (notably) the `from e` cause chain is dropped.","triggerScenarios":"Calling create_or_update_vector_store(online_mode=True, ...) or _init_online_vector_db with a reachable-check failing: wrong port, mistyped hostname, Qdrant Cloud cluster paused/deleted, invalid API key causing an auth error, or an HTTPS/ingress issue. Any exception inside the try block is re-wrapped as this ValueError.","commonSituations":"Qdrant Cloud cluster is paused or its free tier expired; local Docker Qdrant not running (localhost:6333 refused); typo'd URL or using http against an https-only endpoint; rotated API key not updated in env; the lost exception chaining makes the real cause harder to see, prompting developers to debug the wrapper instead of the underlying connection error.","solutions":["Check the underlying service: curl http(s)://<url>/collections or open the URL in a browser to confirm Qdrant is reachable","Fix the endpoint scheme/port (https + :6333 for Qdrant Cloud; http://localhost:6333 for local Docker)","Verify the API key is current and matches the cluster (Qdrant Cloud dashboard > API keys)","Start local Qdrant if using it: docker run -p 6333:6333 qdrant/qdrant"],"exampleFix":"# before\nstore = QdrantVectorStoreManager.create_or_update_vector_store(url=\"https://paused-cluster.cloud.qdrant.io:6333\", online_mode=True, api_key=KEY, model=model, collection_name=\"c\")\n\n# after (verify connectivity first, then retry with a live cluster)\n# curl https://xyz.cloud.qdrant.io:6333/collections -H \"api-key: $KEY\"\nstore = QdrantVectorStoreManager.create_or_update_vector_store(url=\"https://xyz.cloud.qdrant.io:6333\", online_mode=True, api_key=KEY, model=model, collection_name=\"c\")","handlingStrategy":"try-catch","validationCode":"import requests\n\ndef qdrant_reachable(url, api_key=None):\n    try:\n        r = requests.get(f\"{url.rstrip('/')}/collections\", headers={\"api-key\": api_key} if api_key else {}, timeout=5)\n        return r.status_code == 200\n    except requests.RequestException:\n        return False\n\nassert qdrant_reachable(URL, KEY), \"Qdrant server unreachable before initializing\"","typeGuard":null,"tryCatchPattern":"try:\n    store = QdrantVectorStoreManager.create_or_update_vector_store(url=URL, online_mode=True, api_key=KEY, model=m, collection_name=c)\nexcept ValueError as e:\n    msg = str(e)\n    if \"connecting to the server\" in msg:\n        # inspect msg for the root cause (auth, DNS, TLS) and retry after fixing\n        if \"401\" in msg or \"Unauthorized\" in msg:\n            raise SystemExit(\"Bad Qdrant API key\")\n        raise SystemExit(f\"Qdrant unreachable: {msg}\")\n    raise","preventionTips":["Health-check the endpoint (GET /collections) before initializing the store","Ensure local Docker Qdrant is running for localhost URLs; keep cloud clusters unpaused","Validate the URL scheme/port and keep the API key in sync with the cluster","Prefer catching the underlying exception yourself with QdrantClient to get a full traceback, since this wrapper drops the cause chain"],"tags":["qdrant","connection","network","vector-db"],"backgroundTag":"connection-refused","analyzedSha":"fb951af7744dab086e34962e9bc6fe878e145f83","analyzedAt":"2026-08-28T11:56:54.780Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}