{"record":{"id":"50d862ec39b31f4a","repo":"agentscope-ai/agentscope","slug":"vector-search-index-self-index-name-r-on-collec","errorCode":null,"errorMessage":"Vector search index {self._index_name!r} on collection {collection_name!r} was not queryable within {timeout}s","messagePattern":"Vector search index (.+?) on collection (.+?) was not queryable within (.+?)s","errorType":"exception","errorClass":"TimeoutError","httpStatus":null,"severity":"error","filePath":"src/agentscope/rag/_vdb/_mongodb.py","lineNumber":239,"sourceCode":"            timeout (`float`, defaults to ``30.0``):\n                Maximum seconds to wait before raising\n                :class:`TimeoutError`.\n\n        Raises:\n            `TimeoutError`:\n                If the index is not queryable within ``timeout`` seconds.\n        \"\"\"\n        deadline = time.monotonic() + timeout\n        while time.monotonic() < deadline:\n            async for index in await collection.list_search_indexes(\n                self._index_name,\n            ):\n                if index.get(\"queryable\"):\n                    return\n                break\n            await asyncio.sleep(0.5)\n\n        raise TimeoutError(\n            f\"Vector search index {self._index_name!r} on collection \"\n            f\"{collection_name!r} was not queryable within {timeout}s\",\n        )\n\n    async def _ensure_index_ready(self, collection: str) -> None:\n        \"\"\"Ensure the vector search index is queryable before reads.\"\"\"\n        await self._wait_for_index_ready(self._col(collection), collection)\n\n    # ------------------------------------------------------------------\n    # Data operations\n    # ------------------------------------------------------------------\n\n    async def insert(\n        self,\n        collection: str,\n        records: list[VectorRecord],\n    ) -> None:\n        \"\"\"Insert records into a collection.","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/rag/_vdb/_mongodb.py#L221-L257","documentation":"MongoDBVectorDatabase polls the Atlas Search index until it becomes queryable; if it does not within the timeout, TimeoutError is raised by create_collection or before reads via _ensure_index_ready.","triggerScenarios":"Creating/querying a collection whose vector search index is still building, misdefined (wrong field name/path), or was never created on Atlas; slow Atlas index builds exceeding the poll timeout.","commonSituations":"Freshly created Atlas Search index on a large collection; using self-managed MongoDB (no Atlas Search support); index definition referencing the wrong field or similarity metric.","solutions":["Check Atlas UI: index exists, is on the right collection, field path 'vector', and status Active","Increase the timeout passed to the wait call / retry later","Verify you are on MongoDB Atlas with a supported tier (vector search not available on self-managed or free shared tiers in some cases)","Recreate the index definition if the field name doesn't match your documents"],"exampleFix":"# before\nawait vdb.create_collection('docs', dim=768)  # index still building\n# after\nawait vdb.create_collection('docs', dim=768, timeout=600)  # allow longer build","handlingStrategy":"retry","validationCode":"# preflight: index exists and queryable\ninfo = await coll.list_search_indexes()\nready = any(i.get('queryable') for i in info if i.get('name') == index_name)","typeGuard":null,"tryCatchPattern":"for attempt in range(5):\n    try:\n        await vdb.create_collection(name, dim=d, timeout=120)\n        break\n    except TimeoutError:\n        await asyncio.sleep(60)","preventionTips":["Create indexes well before first use on large collections","Verify Atlas tier supports vector search","Double-check index field path matches your document schema"],"tags":["mongodb","atlas","vector-search-index","timeout"],"backgroundTag":"index-not-ready-timeout","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}