vllm-project/vllm · error · ValueError

data_parallel_rank ({self.data_parallel_rank}) must be in th

Error message

data_parallel_rank ({self.data_parallel_rank}) must be in the range [0, {self.data_parallel_size})

What it means

After resolving data_parallel_rank (from args or from RANK for external launchers), ParallelConfig asserts 0 <= data_parallel_rank < data_parallel_size. An out-of-range rank means the process would map to a nonexistent DP slot.

Source

Thrown at vllm/config/parallel.py:887

            if self.distributed_executor_backend == "external_launcher":
                # For external launcher,
                # we need to set the data parallel rank automatically
                self.data_parallel_rank = int(os.environ["RANK"]) // (
                    self.world_size // self.data_parallel_size
                )
                logger.info(
                    "Set data_parallel_rank to %d automatically.",
                    self.data_parallel_rank,
                )
            if not self.enable_elastic_ep:
                if not self._data_parallel_master_port_list:
                    self._data_parallel_master_port_list = get_open_ports_list(5)
                self.data_parallel_master_port = (
                    self._data_parallel_master_port_list.pop()
                )

            if not (0 <= self.data_parallel_rank < self.data_parallel_size):
                raise ValueError(
                    f"data_parallel_rank ({self.data_parallel_rank})"
                    f" must be in the range [0, {self.data_parallel_size})"
                )
        else:
            # Otherwise fall back to env vars (e.g. for offline SPMD case).
            self.data_parallel_size = envs.VLLM_DP_SIZE
            self.data_parallel_rank = envs.VLLM_DP_RANK
            self.data_parallel_rank_local = envs.VLLM_DP_RANK_LOCAL
            self.data_parallel_master_ip = envs.VLLM_DP_MASTER_IP
            self.data_parallel_master_port = envs.VLLM_DP_MASTER_PORT

            if self.data_parallel_size > 1 and self.is_moe_model is False:
                raise ValueError(
                    "Offline data parallel mode is not supported/useful"
                    " for dense models."
                )

        self.data_parallel_index = self.data_parallel_rank

View on GitHub (pinned to c794754062)

Solutions

1. Set --data-parallel-rank to a value in [0, data_parallel_size), e.g. 0 or 1 for dp_size=2.
2. For external_launcher, recheck that RANK/WORLD_SIZE env vars and --data-parallel-size are consistent (world_size == dp_size * tp * pcp * pp).
3. Let vLLM derive the rank automatically (omit --data-parallel-rank) in supported launch modes.

Example fix

# before
vllm serve model --data-parallel-size 2 --data-parallel-rank 2
# after
vllm serve model --data-parallel-size 2 --data-parallel-rank 1

def dp_rank_valid(dp_rank: int, dp_size: int) -> bool:
    return 0 <= dp_rank < dp_size

assert dp_rank_valid(1, 2)

When it happens

Trigger: Explicitly passing --data-parallel-rank R with R >= data_parallel_size or negative; or with external_launcher, when env RANK // (world_size // dp_size) lands outside [0, dp_size) due to mismatched RANK/WORLD_SIZE/DP settings.

Common situations: Mismatched torchrun RANK/WORLD_SIZE versus --data-parallel-size in custom launch scripts; manually editing rank values when debugging a multi-node job; off-by-one errors computing per-node ranks.

Related errors

• data_parallel_size_local ({self.data_parallel_size_local}) m
• data parallel rank {rank} is not connected to this frontend;
• data parallel size must be at least 1
• data parallel size ({}) exceeds the two-byte engine identity
• managed frontend engine count ({engine_count}) must equal da

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