vllm-project/vllm · error · ValueError

numa_bind_nodes must contain non-negative integers.

Error message

numa_bind_nodes must contain non-negative integers.

What it means

The same ParallelConfig field validator rejects any negative integer inside numa_bind_nodes. NUMA node ids are non-negative by definition (as reported by numactl / /sys/devices/system/node), so a negative entry is always a typo or bad arithmetic.

Source

Thrown at vllm/config/parallel.py:422

        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, "
                    "for example '0-3' or '0,2,4-7'."
                )

View on GitHub (pinned to c794754062)

Solutions

1. Check the node ids actually available: numactl --hardware or ls /sys/devices/system/node.
2. Fix the generating script's arithmetic so empty inputs produce an omitted flag, not -1.
3. Pass only ids in [0, max_node], e.g. --numa-bind-nodes 0,1.

Example fix

# before (VAR unset -> -1)
vllm serve model --numa-bind-nodes $((NUM_NODES-1))

# after
vllm serve model --numa-bind-nodes 0,1

def check_numa_nodes(nodes: list[int] | None) -> None:
    if nodes is not None and any(n < 0 for n in nodes):
        raise SystemExit(f"numa_bind_nodes must be non-negative: {nodes}")

def valid_numa_nodes(nodes: list[int] | None) -> bool:
    return nodes is None or (len(nodes) > 0 and all(n >= 0 for n in nodes))

When it happens

Trigger: Passing --numa-bind-nodes -1 or a computed list like [0, -1] (e.g. node_count - 1 style bug producing -1 when count is 0).

Common situations: Off-by-one bugs in generated configs; shell scripts passing $((VAR-1)) when VAR is unset, yielding -1.

Related errors

• numa_bind_nodes must not be empty.
• 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/5008c48216f6fe17. Report an issue: GitHub.