{"record":{"id":"d746b023d5c4632b","repo":"agentscope-ai/agentscope","slug":"num-candidates-must-be-between-1-and-10000","errorCode":null,"errorMessage":"num_candidates must be between 1 and 10000","messagePattern":"num_candidates must be between 1 and 10000","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/rag/_vdb/_elasticsearch.py","lineNumber":60,"sourceCode":"\n        Args:\n            hosts (`str | list[str]`):\n                Elasticsearch URL or list of URLs.\n            num_candidates (`int`, defaults to ``100``):\n                Minimum HNSW candidates considered per shard.  The effective\n                value is raised to ``top_k`` when necessary.\n            refresh (`bool | Literal[\"wait_for\"]`, defaults to \\\n            ``\"wait_for\"``):\n                Refresh policy for writes. Set to ``False`` for higher\n                indexing throughput when immediate search visibility is not\n                required. Elasticsearch's delete-by-query API only accepts a\n                boolean, so ``\"wait_for\"`` maps to ``True`` for deletes.\n            client_kwargs (`dict[str, Any] | None`, optional):\n                Extra arguments forwarded to ``AsyncElasticsearch`` such as\n                ``api_key``, ``basic_auth`` or ``ca_certs``.\n        \"\"\"\n        if num_candidates <= 0 or num_candidates > 10_000:\n            raise ValueError(\"num_candidates must be between 1 and 10000\")\n        self._hosts = hosts\n        self._num_candidates = num_candidates\n        self._refresh = refresh\n        self._client_kwargs = client_kwargs or {}\n        self._client: \"AsyncElasticsearch | None\" = None\n\n    def get_client(self) -> \"AsyncElasticsearch\":\n        \"\"\"Lazily create and cache the shared async client.\"\"\"\n        if self._client is None:\n            from elasticsearch import AsyncElasticsearch\n\n            self._client = AsyncElasticsearch(\n                self._hosts,\n                **self._client_kwargs,\n            )\n        return self._client\n\n    async def __aexit__(","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/rag/_vdb/_elasticsearch.py#L42-L78","documentation":"ElasticsearchVectorDatabase.__init__ requires 1 <= num_candidates <= 10000 for the HNSW approximate kNN search; values outside that range raise ValueError immediately.","triggerScenarios":"ElasticsearchVectorDatabase(num_candidates=0), a negative number, or >10000 (e.g. 20000 copied from a search top_k setting).","commonSituations":"Tuning retrieval quality and assuming num_candidates can be arbitrarily large, or reusing an OpenAI-style parameter with different bounds.","solutions":["Clamp to 10000: num_candidates = min(desired, 10_000)","Use a value between 1 and 10000 (typical 100–1000)","Read num_candidates from config with a bounds check"],"exampleFix":"# before\nvdb = ElasticsearchVectorDatabase(..., num_candidates=50_000)\n# after\nvdb = ElasticsearchVectorDatabase(..., num_candidates=min(50_000, 10_000))","handlingStrategy":"validation","validationCode":"num_candidates = max(1, min(num_candidates, 10_000))","typeGuard":"def valid_num_candidates(n: int) -> bool:\n    return isinstance(n, int) and 1 <= n <= 10_000","tryCatchPattern":null,"preventionTips":["Clamp tuning parameters to documented bounds","Read ES limits from docs when configuring retrieval"],"tags":["elasticsearch","validation","knn","constructor"],"backgroundTag":"invalid-argument-value","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}