vllm-project/vllm · error · ValueError

data_parallel_external_lb can only be set when data_parallel

Error message

data_parallel_external_lb can only be set when data_parallel_size > 1

What it means

An external load balancer for data parallelism (--data-parallel-external-lb) only makes sense when there is more than one data-parallel rank to balance across. ParallelConfig rejects the flag when data_parallel_size <= 1.

Source

Thrown at vllm/config/parallel.py:482

                "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,
            )
            self.all2all_backend = "allgather_reducescatter"

        if self.data_parallel_size_local > self.data_parallel_size:
            raise ValueError(
                f"data_parallel_size_local ({self.data_parallel_size_local}) "
                f"must be <= data_parallel_size ({self.data_parallel_size})"
            )

        if self.data_parallel_size <= 1 and self.data_parallel_external_lb:
            raise ValueError(
                "data_parallel_external_lb can only be set when data_parallel_size > 1"
            )

        if not self.numa_bind and (
            self.numa_bind_nodes is not None or self.numa_bind_cpus is not None
        ):
            raise ValueError(
                "numa_bind_nodes and numa_bind_cpus require numa_bind=True."
            )

        if self.enable_eplb:
            if not current_platform.is_cuda_alike():
                raise ValueError(
                    "Expert parallelism load balancing is only supported on "
                    "CUDA devices or ROCm devices now."
                )
            if not self.enable_expert_parallel:
                raise ValueError("enable_expert_parallel must be True to use EPLB.")

View on GitHub (pinned to c794754062)

Solutions

1. Add --data-parallel-size N (N > 1) to match the external load balancer setup.
2. Or drop --data-parallel-external-lb if you only run a single DP rank; route requests directly to the API server.

Example fix

# before
vllm serve model --data-parallel-external-lb
# after
vllm serve model --data-parallel-size 2 --data-parallel-external-lb

def external_lb_valid(dp_size: int, external_lb: bool) -> bool:
    return not external_lb or dp_size > 1

assert external_lb_valid(2, True)

When it happens

Trigger: Starting vLLM with --data-parallel-external-lb but without --data-parallel-size > 1 (default is 1).

Common situations: Copy-pasting a production-style DP + external LB launch command onto a single-GPU test box; removing the DP flag while debugging but forgetting the LB flag.

Related errors

• data_parallel_size_local ({self.data_parallel_size_local}) m
• PCP does not support data parallelism yet.
• Elastic EP is not compatible with data_parallel_external_lb
• data parallel rank {rank} is not connected to this frontend;
• data parallel size must be at least 1

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