vllm-project/vllm · error · ValueError

Invalid value of `_api_process_rank`. Expected to be `-1` or

Error message

Invalid value of `_api_process_rank`. Expected to be `-1` or `[0, {self._api_process_count})`, but found: {self._api_process_rank}

What it means

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.

Source

Thrown at vllm/config/parallel.py:454

            if not _NUMACTL_CPUSET_PATTERN.fullmatch(cpuset):
                raise ValueError(
                    "numa_bind_cpus entries must use numactl CPU list syntax, "
                    "for example '0-3' or '0,2,4-7'."
                )
            for part in cpuset.split(","):
                if "-" not in part:
                    continue
                start_str, end_str = part.split("-", 1)
                if int(start_str) > int(end_str):
                    raise ValueError(
                        f"numa_bind_cpus ranges must be ascending, but got '{cpuset}'."
                    )
        return value

    @model_validator(mode="after")
    def _validate_parallel_config(self) -> Self:
        if self._api_process_rank >= self._api_process_count:
            raise ValueError(
                "Invalid value of `_api_process_rank`. "
                f"Expected to be `-1` or `[0, {self._api_process_count})`, "
                f"but found: {self._api_process_rank}"
            )

        if self.enable_fault_tolerance and self._api_process_count > 1:
            raise ValueError(
                "Fault tolerance requires a single API server process "
                f"(--api-server-count=1), but got {self._api_process_count}. "
                "The FT system assumes one AsyncMPClient manages all engines."
            )

        if self.all2all_backend in ["pplx", "naive"]:
            logger.warning(
                "The '%s' all2all backend has been removed. "
                "Falling back to 'allgather_reducescatter'.",
                self.all2all_backend,
            )

View on GitHub (pinned to c794754062)

Solutions

1. Set _api_process_rank to -1 when running a single API server process.
2. Otherwise keep it in [0, _api_process_count), e.g. rank 0 or 1 for count 2.
3. Prefer driving multi-API-server mode through the documented --api-server-count flag so vLLM assigns ranks itself.

Example fix

# before
ParallelConfig(_api_process_rank=2, _api_process_count=2)
# after
ParallelConfig(_api_process_rank=1, _api_process_count=2)

def rank_valid(rank: int, count: int) -> bool:
    return rank == -1 or 0 <= rank < count

assert rank_valid(-1, 1) and not rank_valid(2, 2)

When it happens

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

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

Related errors

• Fault tolerance requires a single API server process (--api-
• numa_bind_cpus ranges must be ascending, but got '{cpuset}'.
• data_parallel_size_local ({self.data_parallel_size_local}) m
• data_parallel_external_lb can only be set when data_parallel
• EPLB requires tensor, prefill-context, or data parallelism,

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/77914b2360a27810. Report an issue: GitHub.