vllm-project/vllm · error · ValueError

EPLB requires tensor, prefill-context, or data parallelism,

Error message

EPLB requires tensor, prefill-context, or data parallelism, but got TP={self.tensor_parallel_size}, PCP={self.prefill_context_parallel_size}, DP={self.data_parallel_size}.

What it means

The EP group for EPLB spans TP x PCP x DP ranks, so at least one of those parallel sizes must exceed 1. ParallelConfig computes the product and raises when it is <= 1, i.e. a fully single-rank config asked for EPLB.

Source

Thrown at vllm/config/parallel.py:509

            )

        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.")
            # The EP group spans the TP x PCP x DP ranks. EPLB therefore needs
            # TP, PCP, or DP > 1.
            if (
                self.tensor_parallel_size
                * self.prefill_context_parallel_size
                * self.data_parallel_size
                <= 1
            ):
                raise ValueError(
                    "EPLB requires tensor, prefill-context, or data parallelism, "
                    f"but got TP={self.tensor_parallel_size}, "
                    f"PCP={self.prefill_context_parallel_size}, "
                    f"DP={self.data_parallel_size}."
                )
        else:
            if self.eplb_config.num_redundant_experts != 0:
                raise ValueError(
                    "num_redundant_experts is set to "
                    f"{self.eplb_config.num_redundant_experts} but EPLB is not "
                    "enabled. Either enable EPLB or unset "
                    "num_redundant_experts."
                )

        tp = self.tensor_parallel_size
        pcp = self.prefill_context_parallel_size
        dcp = self.decode_context_parallel_size
        if pcp > 1 and self.data_parallel_size > 1:

View on GitHub (pinned to c794754062)

Solutions

1. Scale out with at least one of --tensor-parallel-size, --data-parallel-size (with expert parallel), or prefill context parallel > 1.
2. For local smoke tests, drop --enable-eplb and only re-enable it on multi-rank deployments.

Example fix

# before
vllm serve Qwen3-MoE --enable-expert-parallel --enable-eplb
# after
vllm serve Qwen3-MoE --tensor-parallel-size 2 --enable-expert-parallel --enable-eplb

def eplb_parallelism_valid(tp: int, pcp: int, dp: int) -> bool:
    return tp * pcp * dp > 1

assert eplb_parallelism_valid(2, 1, 1)

When it happens

Trigger: Single-GPU run (TP=1, PCP=1, DP=1) with --enable-expert-parallel --enable-eplb; any config where tensor_parallel_size * prefill_context_parallel_size * data_parallel_size == 1.

Common situations: Testing EPLB on one GPU before scaling out; shrinking a cluster launch to a single rank for debugging while keeping EPLB flags.

Related errors

• enable_expert_parallel must be True to use EPLB.
• Expert parallelism load balancing is only supported on CUDA
• num_redundant_experts is set to {self.eplb_config.num_redund
• Elastic EP is only supported with enable_eplb=True.
• multimodal preprocessing error: {0}

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