{"record":{"id":"3b5b024570e6ecc1","repo":"vllm-project/vllm","slug":"data-parallel-external-lb-can-only-be-set-when-dat","errorCode":null,"errorMessage":"data_parallel_external_lb can only be set when data_parallel_size > 1","messagePattern":"data_parallel_external_lb can only be set when data_parallel_size > 1","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/parallel.py","lineNumber":482,"sourceCode":"                \"The FT system assumes one AsyncMPClient manages all engines.\"\n            )\n\n        if self.all2all_backend in [\"pplx\", \"naive\"]:\n            logger.warning(\n                \"The '%s' all2all backend has been removed. \"\n                \"Falling back to 'allgather_reducescatter'.\",\n                self.all2all_backend,\n            )\n            self.all2all_backend = \"allgather_reducescatter\"\n\n        if self.data_parallel_size_local > self.data_parallel_size:\n            raise ValueError(\n                f\"data_parallel_size_local ({self.data_parallel_size_local}) \"\n                f\"must be <= data_parallel_size ({self.data_parallel_size})\"\n            )\n\n        if self.data_parallel_size <= 1 and self.data_parallel_external_lb:\n            raise ValueError(\n                \"data_parallel_external_lb can only be set when data_parallel_size > 1\"\n            )\n\n        if not self.numa_bind and (\n            self.numa_bind_nodes is not None or self.numa_bind_cpus is not None\n        ):\n            raise ValueError(\n                \"numa_bind_nodes and numa_bind_cpus require numa_bind=True.\"\n            )\n\n        if self.enable_eplb:\n            if not current_platform.is_cuda_alike():\n                raise ValueError(\n                    \"Expert parallelism load balancing is only supported on \"\n                    \"CUDA devices or ROCm devices now.\"\n                )\n            if not self.enable_expert_parallel:\n                raise ValueError(\"enable_expert_parallel must be True to use EPLB.\")","sourceCodeStart":464,"sourceCodeEnd":500,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/parallel.py#L464-L500","documentation":"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.","triggerScenarios":"Starting vLLM with --data-parallel-external-lb but without --data-parallel-size > 1 (default is 1).","commonSituations":"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.","solutions":["Add --data-parallel-size N (N > 1) to match the external load balancer setup.","Or drop --data-parallel-external-lb if you only run a single DP rank; route requests directly to the API server."],"exampleFix":"# before\nvllm serve model --data-parallel-external-lb\n# after\nvllm serve model --data-parallel-size 2 --data-parallel-external-lb","handlingStrategy":"validation","validationCode":"def external_lb_valid(dp_size: int, external_lb: bool) -> bool:\n    return not external_lb or dp_size > 1\n\nassert external_lb_valid(2, True)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair --data-parallel-external-lb with an explicit --data-parallel-size > 1 in the same template.","Strip advanced DP flags when downgrading a launch to a single GPU."],"tags":["data-parallel","load-balancing","configuration","parallelism"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}