vllm-project/vllm · error · ValueError

numa_bind_nodes and numa_bind_cpus require numa_bind=True.

Error message

numa_bind_nodes and numa_bind_cpus require numa_bind=True.

What it means

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.

Source

Thrown at vllm/config/parallel.py:489

                self.all2all_backend,
            )
            self.all2all_backend = "allgather_reducescatter"

        if self.data_parallel_size_local > self.data_parallel_size:
            raise ValueError(
                f"data_parallel_size_local ({self.data_parallel_size_local}) "
                f"must be <= data_parallel_size ({self.data_parallel_size})"
            )

        if self.data_parallel_size <= 1 and self.data_parallel_external_lb:
            raise ValueError(
                "data_parallel_external_lb can only be set when data_parallel_size > 1"
            )

        if not self.numa_bind and (
            self.numa_bind_nodes is not None or self.numa_bind_cpus is not None
        ):
            raise ValueError(
                "numa_bind_nodes and numa_bind_cpus require numa_bind=True."
            )

        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

View on GitHub (pinned to c794754062)

Solutions

1. Add --numa-bind alongside the node/CPU lists: --numa-bind --numa-bind-cpus 0-3.
2. Or remove the numa_bind_nodes / numa_bind_cpus entries if NUMA pinning was not intended.

Example fix

# before
vllm serve model --numa-bind-cpus 0-3
# after
vllm serve model --numa-bind --numa-bind-cpus 0-3

def numa_config_valid(numa_bind: bool, nodes, cpus) -> bool:
    return numa_bind or (nodes is None and cpus is None)

assert numa_config_valid(True, [0], None)

When it happens

Trigger: Passing --numa-bind-cpus 0-3 or --numa-bind-nodes 0 without --numa-bind (defaults to False).

Common situations: 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.

Related errors

• numa_bind_cpus ranges must be ascending, but got '{cpuset}'.
• {kind} parser `{name}` is not registered{}
• gpt_oss uses native Harmony output parsing; generic {kind} p
• failed to read chat template file
• chat template looks like a file path but does not exist

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