vllm-project/vllm · error · ValueError

numa_bind_nodes must not be empty.

Error message

numa_bind_nodes must not be empty.

What it means

ParallelConfig's field validator for numa_bind_nodes treats an explicitly provided empty list as invalid: None means 'not set', but [] would ask the NUMA binding code to bind to zero nodes, which is meaningless. Any non-None value must contain at least one node id.

Source

Thrown at vllm/config/parallel.py:420

    fault_tolerance_config: FaultToleranceConfig = Field(
        default_factory=FaultToleranceConfig
    )
    """The configurations for fault tolerance."""

    @field_validator("disable_nccl_for_dp_synchronization", mode="wrap")
    @classmethod
    def _skip_none_validation(cls, value: Any, handler: Callable) -> Any:
        """Skip validation if the value is `None` when initialisation is delayed."""
        return None if value is None else handler(value)

    @field_validator("numa_bind_nodes")
    @classmethod
    def _validate_numa_bind_nodes(cls, value: list[int] | None) -> list[int] | None:
        if value is None:
            return None
        if not value:
            raise ValueError("numa_bind_nodes must not be empty.")
        if any(node < 0 for node in value):
            raise ValueError("numa_bind_nodes must contain non-negative integers.")
        return value

    @field_validator("numa_bind_cpus")
    @classmethod
    def _validate_numa_bind_cpus(cls, value: list[str] | None) -> list[str] | None:
        if value is None:
            return None
        if not value:
            raise ValueError("numa_bind_cpus must not be empty.")

        for cpuset in value:
            if not cpuset:
                raise ValueError("numa_bind_cpus entries must not be empty.")
            if not _NUMACTL_CPUSET_PATTERN.fullmatch(cpuset):
                raise ValueError(
                    "numa_bind_cpus entries must use numactl CPU list syntax, "

View on GitHub (pinned to c794754062)

Solutions

1. Omit --numa-bind-nodes entirely when you do not want NUMA binding (None is valid and means unset).
2. Otherwise pass at least one valid node, e.g. --numa-bind-nodes 0 or 0,1.
3. Fix the templating so empty values drop the flag instead of emitting an empty list.

Example fix

# before (empty env var)
vllm serve model --numa-bind-nodes "${NUMA_NODES}"  # NUMA_NODES="" -> []

# after
# only add the flag when non-empty:
vllm serve model --numa-bind-nodes 0,1

def normalize_numa_nodes(v: list[int] | None) -> list[int] | None:
    return None if not v else v  # drop empty list instead of passing it on

When it happens

Trigger: Passing --numa-bind-nodes with an empty value that parses to [] (e.g. an empty CSV/JSON list), or ParallelConfig(numa_bind_nodes=[]) in Python code; template scripts that interpolate an empty variable into the flag.

Common situations: Helm/Kubernetes templates rendering --numa-bind-nodes="${NODES}" where NODES is empty; config generators emitting [] instead of omitting the field.

Related errors

• numa_bind_nodes must contain non-negative integers.
• numa_bind_cpus must not be empty.
• numa_bind_cpus entries must not be empty.
• numa_bind_cpus entries must use numactl CPU list syntax, for
• 'mm_shm_cache_max_object_size_mb' should only be set when 'm

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