agentscope-ai/agentscope · error · ValueError

num_candidates must be between 1 and 10000

Error message

num_candidates must be between 1 and 10000

What it means

ElasticsearchVectorDatabase.__init__ requires 1 <= num_candidates <= 10000 for the HNSW approximate kNN search; values outside that range raise ValueError immediately.

Source

Thrown at src/agentscope/rag/_vdb/_elasticsearch.py:60

        Args:
            hosts (`str | list[str]`):
                Elasticsearch URL or list of URLs.
            num_candidates (`int`, defaults to ``100``):
                Minimum HNSW candidates considered per shard.  The effective
                value is raised to ``top_k`` when necessary.
            refresh (`bool | Literal["wait_for"]`, defaults to \
            ``"wait_for"``):
                Refresh policy for writes. Set to ``False`` for higher
                indexing throughput when immediate search visibility is not
                required. Elasticsearch's delete-by-query API only accepts a
                boolean, so ``"wait_for"`` maps to ``True`` for deletes.
            client_kwargs (`dict[str, Any] | None`, optional):
                Extra arguments forwarded to ``AsyncElasticsearch`` such as
                ``api_key``, ``basic_auth`` or ``ca_certs``.
        """
        if num_candidates <= 0 or num_candidates > 10_000:
            raise ValueError("num_candidates must be between 1 and 10000")
        self._hosts = hosts
        self._num_candidates = num_candidates
        self._refresh = refresh
        self._client_kwargs = client_kwargs or {}
        self._client: "AsyncElasticsearch | None" = None

    def get_client(self) -> "AsyncElasticsearch":
        """Lazily create and cache the shared async client."""
        if self._client is None:
            from elasticsearch import AsyncElasticsearch

            self._client = AsyncElasticsearch(
                self._hosts,
                **self._client_kwargs,
            )
        return self._client

    async def __aexit__(

View on GitHub (pinned to e90f1c7592)

Solutions

1. Clamp to 10000: num_candidates = min(desired, 10_000)
2. Use a value between 1 and 10000 (typical 100–1000)
3. Read num_candidates from config with a bounds check

Example fix

# before
vdb = ElasticsearchVectorDatabase(..., num_candidates=50_000)
# after
vdb = ElasticsearchVectorDatabase(..., num_candidates=min(50_000, 10_000))

num_candidates = max(1, min(num_candidates, 10_000))

def valid_num_candidates(n: int) -> bool:
    return isinstance(n, int) and 1 <= n <= 10_000

When it happens

Trigger: ElasticsearchVectorDatabase(num_candidates=0), a negative number, or >10000 (e.g. 20000 copied from a search top_k setting).

Common situations: Tuning retrieval quality and assuming num_candidates can be arbitrarily large, or reusing an OpenAI-style parameter with different bounds.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• top_k cannot exceed Elasticsearch's 10000 limit
• "Mem0Middleware requires a non-empty `user_id`."
• The table_format must be one of 'markdown' or 'json', got {t
• Either client_gen or session must be provided, but not both.
• The tool group description is required for tool group '{name

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