vllm-project/vllm · error · ValueError

numa_bind_cpus ranges must be ascending, but got '{cpuset}'.

Error message

numa_bind_cpus ranges must be ascending, but got '{cpuset}'.

What it means

ParallelConfig validates each entry of numa_bind_cpus against numactl CPU-list syntax. A range segment like '3-0' whose start CPU number is greater than its end CPU number is rejected because numactl itself requires ascending ranges. The check runs per-entry inside the field validator before the model-level cross-field validation.

Source

Thrown at vllm/config/parallel.py:446

        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`. "
                f"Expected to be `-1` or `[0, {self._api_process_count})`, "
                f"but found: {self._api_process_rank}"
            )

        if self.enable_fault_tolerance and self._api_process_count > 1:
            raise ValueError(
                "Fault tolerance requires a single API server process "
                f"(--api-server-count=1), but got {self._api_process_count}. "
                "The FT system assumes one AsyncMPClient manages all engines."

View on GitHub (pinned to c794754062)

Solutions

1. Rewrite the range in ascending order, e.g. replace '3-0' with '0-3'.
2. If the intent is an unordered CPU set, list single CPUs comma-separated ('0,3,7') instead of ranges.
3. Verify the final string against numactl syntax: run `numactl --show` or `numactl -C <cpuset> true` to confirm the kernel accepts it before passing it to vLLM.

Example fix

# before
--numa-bind-cpus 3-0
# after
--numa-bind-cpus 0-3

import re

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

def cpusets_valid(entries: list[str]) -> bool:
    return all(
        NUMACTL.fullmatch(c) and all(
            "-" not in p or int(p.split("-")[0]) <= int(p.split("-")[1])
            for p in c.split(",")
        )
        for c in entries
    )

assert cpusets_valid(["0-3", "0,2,4-7"])

When it happens

Trigger: Setting --numa-bind-cpus with a descending or reversed range, e.g. 'vllm serve ... --numa-bind-cpus 3-0' or '0,7-4'. Any comma-separated part containing '-' where int(start) > int(end) triggers it.

Common situations: Typing a CPU range backwards when mirroring a NUMA topology; copying a cpuset from /proc or taskset output that lists CPUs in a different order and hand-editing it into a range.

Related errors

• numa_bind_nodes and numa_bind_cpus require numa_bind=True.
• Invalid value of `_api_process_rank`. Expected to be `-1` or
• Fault tolerance requires a single API server process (--api-
• data_parallel_size_local ({self.data_parallel_size_local}) m
• data_parallel_external_lb can only be set when data_parallel

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