{"record":{"id":"77914b2360a27810","repo":"vllm-project/vllm","slug":"invalid-value-of-api-process-rank-expected-to","errorCode":null,"errorMessage":"Invalid value of `_api_process_rank`. Expected to be `-1` or `[0, {self._api_process_count})`, but found: {self._api_process_rank}","messagePattern":"Invalid value of `_api_process_rank`\\. Expected to be `-1` or `\\[0, (.+?)\\)`, but found: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/parallel.py","lineNumber":454,"sourceCode":"            if not _NUMACTL_CPUSET_PATTERN.fullmatch(cpuset):\n                raise ValueError(\n                    \"numa_bind_cpus entries must use numactl CPU list syntax, \"\n                    \"for example '0-3' or '0,2,4-7'.\"\n                )\n            for part in cpuset.split(\",\"):\n                if \"-\" not in part:\n                    continue\n                start_str, end_str = part.split(\"-\", 1)\n                if int(start_str) > int(end_str):\n                    raise ValueError(\n                        f\"numa_bind_cpus ranges must be ascending, but got '{cpuset}'.\"\n                    )\n        return value\n\n    @model_validator(mode=\"after\")\n    def _validate_parallel_config(self) -> Self:\n        if self._api_process_rank >= self._api_process_count:\n            raise ValueError(\n                \"Invalid value of `_api_process_rank`. \"\n                f\"Expected to be `-1` or `[0, {self._api_process_count})`, \"\n                f\"but found: {self._api_process_rank}\"\n            )\n\n        if self.enable_fault_tolerance and self._api_process_count > 1:\n            raise ValueError(\n                \"Fault tolerance requires a single API server process \"\n                f\"(--api-server-count=1), but got {self._api_process_count}. \"\n                \"The FT system assumes one AsyncMPClient manages all engines.\"\n            )\n\n        if self.all2all_backend in [\"pplx\", \"naive\"]:\n            logger.warning(\n                \"The '%s' all2all backend has been removed. \"\n                \"Falling back to 'allgather_reducescatter'.\",\n                self.all2all_backend,\n            )","sourceCodeStart":436,"sourceCodeEnd":472,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/parallel.py#L436-L472","documentation":"After model validation, ParallelConfig checks the private field _api_process_rank against _api_process_count. Any rank >= count (with -1 meaning 'unset/single process') is rejected because the rank indexes into the set of API server processes. This is an internal field normally derived by vLLM when spawning multiple API servers, not a public CLI flag.","triggerScenarios":"Programmatically constructing ParallelConfig (or a subclass) with _api_process_rank >= _api_process_count, e.g. rank=2 with count=2. Not reachable through standard CLI flags.","commonSituations":"Code that manually spawns vLLM API server processes and injects rank/count values; stale internal code after refactoring renamed the public flag (--api-server-count) while a caller still sets the old private pair inconsistently.","solutions":["Set _api_process_rank to -1 when running a single API server process.","Otherwise keep it in [0, _api_process_count), e.g. rank 0 or 1 for count 2.","Prefer driving multi-API-server mode through the documented --api-server-count flag so vLLM assigns ranks itself."],"exampleFix":"# before\nParallelConfig(_api_process_rank=2, _api_process_count=2)\n# after\nParallelConfig(_api_process_rank=1, _api_process_count=2)","handlingStrategy":"validation","validationCode":"def rank_valid(rank: int, count: int) -> bool:\n    return rank == -1 or 0 <= rank < count\n\nassert rank_valid(-1, 1) and not rank_valid(2, 2)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat _api_process_rank/_api_process_count as an internally managed pair; drive them via --api-server-count.","Assert rank == -1 or 0 <= rank < count immediately after computing them in custom spawners."],"tags":["api-server","configuration","internal","parallelism"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}