vllm-project/vllm · error · ValueError

Async EPLB is only supported with the default policy.

Error message

Async EPLB is only supported with the default policy.

What it means

EPLBConfig's post-init validator rejects use_async=True combined with any policy other than 'default'. Async expert-parallel load balancing only works with the default balancedness policy; statistics-based or other policies require synchronous rebalancing.

Source

Thrown at vllm/config/parallel.py:105

    """

    policy: EPLBPolicyOption = "default"
    """The policy type for expert parallel load balancing (EPLB)."""

    communicator: EPLBCommunicatorBackend | None = None
    """
    Backend for EPLB expert weight communication:
    - "torch_nccl": Use torch.distributed on the device process group
    - "torch_gloo": Use torch.distributed gloo with CPU staging
    - "nixl": Use NIXL with staged send/recv buffers
    - "pynccl": Use PyNccl send/recv
    - None: Auto-select backend (prefers "nixl", falls back to "torch_gloo")
    """

    @model_validator(mode="after")
    def _validate_eplb_config(self) -> Self:
        if self.use_async and self.policy != "default":
            raise ValueError("Async EPLB is only supported with the default policy.")
        if self.use_async and self.communicator in ("torch_nccl", "pynccl"):
            raise ValueError(
                f"{self.communicator} communicator is incompatible with "
                "async EPLB due to NCCL multi-stream conflicts. Use "
                "'torch_gloo' or 'nixl' instead, or leave communicator "
                "unset for automatic selection."
            )
        if self.log_balancedness and self.log_balancedness_interval <= 0:
            raise ValueError("log_balancedness_interval must be greater than 0.")
        return self


@config
class ParallelConfig:
    """Configuration for the distributed execution."""

    pipeline_parallel_size: int = Field(default=1, ge=1)
    """Number of pipeline parallel groups."""

View on GitHub (pinned to c794754062)

Solutions

1. Drop --async-eplb (keep your policy) and accept synchronous rebalancing.
2. Or keep async EPLB and set --eplb-policy default.
3. Check the EPLB docs for your vLLM version to see which policies support async operation.

Example fix

# before
vllm serve DeepSeek-ai/DeepSeek-V3 --enable-eplb --async-eplb --eplb-policy eplb_dynamic

# after
vllm serve DeepSeek-ai/DeepSeek-V3 --enable-eplb --async-eplb --eplb-policy default

def check_async_eplb(use_async: bool, policy: str) -> None:
    if use_async and policy != "default":
        raise SystemExit("Async EPLB requires --eplb-policy default")

When it happens

Trigger: Passing --enable-eplb --async-eplb with --eplb-policy eplb_dynamic (or any non-'default' policy string) on a MoE model.

Common situations: Copying an advanced EPLB config (which uses a dynamic policy) and adding --async-eplb to reduce sync overhead; upgrading vLLM where async EPLB changed its supported policy set.

Related errors

• {self.communicator} communicator is incompatible with async
• log_balancedness_interval must be greater than 0.
• multimodal preprocessing error: {0}
• 'mm_shm_cache_max_object_size_mb' should only be set when 'm
• 'mm_encoder_fp8_scale_path' and 'mm_encoder_fp8_scale_save_p

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