{"record":{"id":"1a762d593b613999","repo":"vllm-project/vllm","slug":"numa-bind-nodes-and-numa-bind-cpus-require-numa-bi","errorCode":null,"errorMessage":"numa_bind_nodes and numa_bind_cpus require numa_bind=True.","messagePattern":"numa_bind_nodes and numa_bind_cpus require numa_bind=True\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/parallel.py","lineNumber":489,"sourceCode":"                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.\")\n            # The EP group spans the TP x PCP x DP ranks. EPLB therefore needs\n            # TP, PCP, or DP > 1.\n            if (\n                self.tensor_parallel_size\n                * self.prefill_context_parallel_size\n                * self.data_parallel_size\n                <= 1","sourceCodeStart":471,"sourceCodeEnd":507,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/parallel.py#L471-L507","documentation":"numa_bind_nodes and numa_bind_cpus are subordinate knobs that refine --numa-bind; specifying either without numa_bind=True is a contradiction, so ParallelConfig refuses the config. NUMA pinning must be explicitly enabled before node/CPU-level directives are accepted.","triggerScenarios":"Passing --numa-bind-cpus 0-3 or --numa-bind-nodes 0 without --numa-bind (defaults to False).","commonSituations":"Assuming the fine-grained flags imply NUMA binding; migrating from an older/newer CLI where numa_bind was implied; typo'd --numa-bind flag that silently parses as an unknown argument and gets dropped.","solutions":["Add --numa-bind alongside the node/CPU lists: --numa-bind --numa-bind-cpus 0-3.","Or remove the numa_bind_nodes / numa_bind_cpus entries if NUMA pinning was not intended."],"exampleFix":"# before\nvllm serve model --numa-bind-cpus 0-3\n# after\nvllm serve model --numa-bind --numa-bind-cpus 0-3","handlingStrategy":"validation","validationCode":"def numa_config_valid(numa_bind: bool, nodes, cpus) -> bool:\n    return numa_bind or (nodes is None and cpus is None)\n\nassert numa_config_valid(True, [0], None)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always emit --numa-bind as the first flag of any NUMA group.","Wrap NUMA flags in one template variable block so they are added or removed together."],"tags":["numa","cpu-affinity","configuration"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}