{"record":{"id":"366d34c69c1c9563","repo":"vllm-project/vllm","slug":"numa-bind-cpus-entries-must-use-numactl-cpu-list-s","errorCode":null,"errorMessage":"numa_bind_cpus entries must use numactl CPU list syntax, for example '0-3' or '0,2,4-7'.","messagePattern":"numa_bind_cpus entries must use numactl CPU list syntax, for example '0-3' or '0,2,4-7'\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/parallel.py","lineNumber":437,"sourceCode":"        if not value:\n            raise ValueError(\"numa_bind_nodes must not be empty.\")\n        if any(node < 0 for node in value):\n            raise ValueError(\"numa_bind_nodes must contain non-negative integers.\")\n        return value\n\n    @field_validator(\"numa_bind_cpus\")\n    @classmethod\n    def _validate_numa_bind_cpus(cls, value: list[str] | None) -> list[str] | None:\n        if value is None:\n            return None\n        if not value:\n            raise ValueError(\"numa_bind_cpus must not be empty.\")\n\n        for cpuset in value:\n            if not cpuset:\n                raise ValueError(\"numa_bind_cpus entries must not be empty.\")\n            if not _NUMACTL_CPUSET_PATTERN.fullmatch(cpuset):\n                raise ValueError(\n                    \"numa_bind_cpus entries must use numactl CPU list syntax, \"\n                    \"for example '0-3' or '0,2,4-7'.\"\n                )\n            for part in cpuset.split(\",\"):\n                if \"-\" not in part:\n                    continue\n                start_str, end_str = part.split(\"-\", 1)\n                if int(start_str) > int(end_str):\n                    raise ValueError(\n                        f\"numa_bind_cpus ranges must be ascending, but got '{cpuset}'.\"\n                    )\n        return value\n\n    @model_validator(mode=\"after\")\n    def _validate_parallel_config(self) -> Self:\n        if self._api_process_rank >= self._api_process_count:\n            raise ValueError(\n                \"Invalid value of `_api_process_rank`. \"","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/parallel.py#L419-L455","documentation":"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.","triggerScenarios":"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.","commonSituations":"Confusing numactl CPU lists with taskset hex masks or cgroup cpuset syntax (which adds 'cpu:' prefixes); whitespace inside quoted values; OCR/copy-paste artifacts.","solutions":["Rewrite the value in numactl syntax: only decimal numbers, ranges with '-', and comma separation, e.g. 0,2,4-7.","If you have a hex mask, convert it first: taskset -c outputs or python bin(int('ff',16)) enumeration to a CPU list.","Strip whitespace and stray characters when generating the string programmatically."],"exampleFix":"# before\nvllm serve model --numa-bind-cpus 0xff\n\n# after\nvllm serve model --numa-bind-cpus 0-7","handlingStrategy":"type-guard","validationCode":"import re\nNUMACTL = re.compile(r\"^\\d+(?:-\\d+)?(?:,\\d+(?:-\\d+)?)*$\")\n\ndef validate_cpuset(cpuset: str) -> str:\n    if not NUMACTL.fullmatch(cpuset):\n        raise SystemExit(f\"{cpuset!r} is not numactl syntax (e.g. '0-3' or '0,2,4-7')\")\n    return cpuset","typeGuard":"def is_numactl_cpuset(s: str) -> bool:\n    return bool(re.fullmatch(r\"\\d+(?:-\\d+)?(?:,\\d+(?:-\\d+)?)*\", s))","tryCatchPattern":null,"preventionTips":["Convert taskset hex masks to decimal CPU lists before passing them to vLLM.","Never mix cgroup ('cpu:0-3') or space-separated syntax into --numa-bind-cpus."],"tags":["vllm","config","numa","cpuset","regex","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}