agentscope-ai/agentscope · error · TimeoutError

Vector search index {self._index_name!r} on collection {coll

Error message

Vector search index {self._index_name!r} on collection {collection_name!r} was not queryable within {timeout}s

What it means

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.

Source

Thrown at src/agentscope/rag/_vdb/_mongodb.py:239

            timeout (`float`, defaults to ``30.0``):
                Maximum seconds to wait before raising
                :class:`TimeoutError`.

        Raises:
            `TimeoutError`:
                If the index is not queryable within ``timeout`` seconds.
        """
        deadline = time.monotonic() + timeout
        while time.monotonic() < deadline:
            async for index in await collection.list_search_indexes(
                self._index_name,
            ):
                if index.get("queryable"):
                    return
                break
            await asyncio.sleep(0.5)

        raise TimeoutError(
            f"Vector search index {self._index_name!r} on collection "
            f"{collection_name!r} was not queryable within {timeout}s",
        )

    async def _ensure_index_ready(self, collection: str) -> None:
        """Ensure the vector search index is queryable before reads."""
        await self._wait_for_index_ready(self._col(collection), collection)

    # ------------------------------------------------------------------
    # Data operations
    # ------------------------------------------------------------------

    async def insert(
        self,
        collection: str,
        records: list[VectorRecord],
    ) -> None:
        """Insert records into a collection.

View on GitHub (pinned to e90f1c7592)

Solutions

1. Check Atlas UI: index exists, is on the right collection, field path 'vector', and status Active
2. Increase the timeout passed to the wait call / retry later
3. Verify you are on MongoDB Atlas with a supported tier (vector search not available on self-managed or free shared tiers in some cases)
4. Recreate the index definition if the field name doesn't match your documents

Example fix

# before
await vdb.create_collection('docs', dim=768)  # index still building
# after
await vdb.create_collection('docs', dim=768, timeout=600)  # allow longer build

# preflight: index exists and queryable
info = await coll.list_search_indexes()
ready = any(i.get('queryable') for i in info if i.get('name') == index_name)

for attempt in range(5):
    try:
        await vdb.create_collection(name, dim=d, timeout=120)
        break
    except TimeoutError:
        await asyncio.sleep(60)

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Ripgrep search timed out after {timeout} seconds. Try search
• CosyVoice TTS synthesis timed out after 30s
• PVC {pvc_name!r} did not finish deleting within {timeout}s

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/50d862ec39b31f4a. Report an issue: GitHub.