{"record":{"id":"3a9eda12220f6b5d","repo":"vllm-project/vllm","slug":"async-eplb-is-only-supported-with-the-default-poli","errorCode":null,"errorMessage":"Async EPLB is only supported with the default policy.","messagePattern":"Async EPLB is only supported with the default policy\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/parallel.py","lineNumber":105,"sourceCode":"    \"\"\"\n\n    policy: EPLBPolicyOption = \"default\"\n    \"\"\"The policy type for expert parallel load balancing (EPLB).\"\"\"\n\n    communicator: EPLBCommunicatorBackend | None = None\n    \"\"\"\n    Backend for EPLB expert weight communication:\n    - \"torch_nccl\": Use torch.distributed on the device process group\n    - \"torch_gloo\": Use torch.distributed gloo with CPU staging\n    - \"nixl\": Use NIXL with staged send/recv buffers\n    - \"pynccl\": Use PyNccl send/recv\n    - None: Auto-select backend (prefers \"nixl\", falls back to \"torch_gloo\")\n    \"\"\"\n\n    @model_validator(mode=\"after\")\n    def _validate_eplb_config(self) -> Self:\n        if self.use_async and self.policy != \"default\":\n            raise ValueError(\"Async EPLB is only supported with the default policy.\")\n        if self.use_async and self.communicator in (\"torch_nccl\", \"pynccl\"):\n            raise ValueError(\n                f\"{self.communicator} communicator is incompatible with \"\n                \"async EPLB due to NCCL multi-stream conflicts. Use \"\n                \"'torch_gloo' or 'nixl' instead, or leave communicator \"\n                \"unset for automatic selection.\"\n            )\n        if self.log_balancedness and self.log_balancedness_interval <= 0:\n            raise ValueError(\"log_balancedness_interval must be greater than 0.\")\n        return self\n\n\n@config\nclass ParallelConfig:\n    \"\"\"Configuration for the distributed execution.\"\"\"\n\n    pipeline_parallel_size: int = Field(default=1, ge=1)\n    \"\"\"Number of pipeline parallel groups.\"\"\"","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/parallel.py#L87-L123","documentation":"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.","triggerScenarios":"Passing --enable-eplb --async-eplb with --eplb-policy eplb_dynamic (or any non-'default' policy string) on a MoE model.","commonSituations":"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.","solutions":["Drop --async-eplb (keep your policy) and accept synchronous rebalancing.","Or keep async EPLB and set --eplb-policy default.","Check the EPLB docs for your vLLM version to see which policies support async operation."],"exampleFix":"# before\nvllm serve DeepSeek-ai/DeepSeek-V3 --enable-eplb --async-eplb --eplb-policy eplb_dynamic\n\n# after\nvllm serve DeepSeek-ai/DeepSeek-V3 --enable-eplb --async-eplb --eplb-policy default","handlingStrategy":"validation","validationCode":"def check_async_eplb(use_async: bool, policy: str) -> None:\n    if use_async and policy != \"default\":\n        raise SystemExit(\"Async EPLB requires --eplb-policy default\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When enabling --async-eplb on an existing config, audit all other eplb-* flags.","Treat policy != 'default' and use_async as mutually exclusive in config schemas."],"tags":["vllm","config","eplb","moe","load-balancing","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}