vllm-project/vllm · error · ValueError

numa_bind_cpus entries must use numactl CPU list syntax, for

Error message

numa_bind_cpus entries must use numactl CPU list syntax, for example '0-3' or '0,2,4-7'.

What it means

Each numa_bind_cpus entry must fully match the numactl CPU-list regex ^\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$ — numbers and ranges like '0-3' or '0,2,4-7'. Anything else (letters, spaces, 'all', hex, '0-3,') fails fullmatch and is rejected with guidance toward the expected syntax.

Source

Thrown at vllm/config/parallel.py:437

        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'."
                )
            for part in cpuset.split(","):
                if "-" not in part:
                    continue
                start_str, end_str = part.split("-", 1)
                if int(start_str) > int(end_str):
                    raise ValueError(
                        f"numa_bind_cpus ranges must be ascending, but got '{cpuset}'."
                    )
        return value

    @model_validator(mode="after")
    def _validate_parallel_config(self) -> Self:
        if self._api_process_rank >= self._api_process_count:
            raise ValueError(
                "Invalid value of `_api_process_rank`. "

View on GitHub (pinned to c794754062)

Solutions

1. Rewrite the value in numactl syntax: only decimal numbers, ranges with '-', and comma separation, e.g. 0,2,4-7.
2. If you have a hex mask, convert it first: taskset -c outputs or python bin(int('ff',16)) enumeration to a CPU list.
3. Strip whitespace and stray characters when generating the string programmatically.

Example fix

# before
vllm serve model --numa-bind-cpus 0xff

# after
vllm serve model --numa-bind-cpus 0-7

import re
NUMACTL = re.compile(r"^\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$")

def validate_cpuset(cpuset: str) -> str:
    if not NUMACTL.fullmatch(cpuset):
        raise SystemExit(f"{cpuset!r} is not numactl syntax (e.g. '0-3' or '0,2,4-7')")
    return cpuset

def is_numactl_cpuset(s: str) -> bool:
    return bool(re.fullmatch(r"\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*", s))

When it happens

Trigger: Passing --numa-bind-cpus all, '0 1 2' (space separated), 'cpu0-3', '0..3', or a trailing comma '0-3,'; also values copied from taskset's hexadecimal mask format (e.g. '0xff') which numactl does not accept.

Common situations: Confusing numactl CPU lists with taskset hex masks or cgroup cpuset syntax (which adds 'cpu:' prefixes); whitespace inside quoted values; OCR/copy-paste artifacts.

Related errors

• numa_bind_cpus must not be empty.
• numa_bind_cpus entries must not be empty.
• numa_bind_nodes must not be empty.
• numa_bind_nodes must contain non-negative integers.
• '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/366d34c69c1c9563. Report an issue: GitHub.