{"record":{"id":"ee050b9eeff42440","repo":"vllm-project/vllm","slug":"expected-128-bytes-for-nccluniqueid-got-len-data","errorCode":null,"errorMessage":"Expected 128 bytes for ncclUniqueId, got {len(data)} bytes","messagePattern":"Expected 128 bytes for ncclUniqueId, got (.+?) bytes","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/device_communicators/pynccl_wrapper.py","lineNumber":440,"sourceCode":"        # something like 21903\n        return version.value\n\n    def ncclGetVersion(self) -> str:\n        version_str = str(self.ncclGetRawVersion())\n        # something like 21903 --> \"2.19.3\"\n        major = version_str[0].lstrip(\"0\")\n        minor = version_str[1:3].lstrip(\"0\")\n        patch = version_str[3:].lstrip(\"0\")\n        return f\"{major}.{minor}.{patch}\"\n\n    def ncclGetUniqueId(self) -> ncclUniqueId:\n        unique_id = ncclUniqueId()\n        self.NCCL_CHECK(self._funcs[\"ncclGetUniqueId\"](ctypes.byref(unique_id)))\n        return unique_id\n\n    def unique_id_from_bytes(self, data: bytes) -> ncclUniqueId:\n        if len(data) != 128:\n            raise ValueError(\n                f\"Expected 128 bytes for ncclUniqueId, got {len(data)} bytes\"\n            )\n        unique_id = ncclUniqueId()\n        ctypes.memmove(ctypes.addressof(unique_id.internal), data, 128)\n        return unique_id\n\n    def ncclCommInitRank(\n        self, world_size: int, unique_id: ncclUniqueId, rank: int\n    ) -> ncclComm_t:\n        comm = ncclComm_t()\n        self.NCCL_CHECK(\n            self._funcs[\"ncclCommInitRank\"](\n                ctypes.byref(comm), world_size, unique_id, rank\n            )\n        )\n        return comm\n\n    def ncclAllReduce(","sourceCodeStart":422,"sourceCodeEnd":458,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/device_communicators/pynccl_wrapper.py#L422-L458","documentation":"NCCLLibrary.unique_id_from_bytes reconstructs an ncclUniqueId from a serialized blob. NCCL unique ids are a fixed 128-byte structure (NCCL_UNIQUE_ID_BYTES), so the loader validates len(data) == 128 before ctypes.memmove; any other length is rejected rather than read out of bounds.","triggerScenarios":"Passing the hex-encoded string of the id (256 chars) instead of raw bytes; passing a Python list/array of ints; slicing a combined broadcast payload incorrectly so the id segment is truncated or includes extra bytes; a string that was never .encode()d/decoded consistently across ranks.","commonSituations":"Hand-rolling unique-id exchange over Ray actors, HTTP, or a store where bytes get re-encoded (str(uid) on Python 2/3 mixing, base64 without decode); versions of a launcher that changed the serialization format.","solutions":["Send exactly bytes(unique_id.internal) (128 raw bytes) and feed that back into unique_id_from_bytes","If transporting as text, hex-encode and unhexlify on the other side: bytes.fromhex(uid_hex)","Length-check the payload before calling: assert len(data) == 128"],"exampleFix":"# before\nuid_hex = bytes(uid.internal).hex()\nlib.unique_id_from_bytes(uid_hex)  # len 256 -> ValueError\n\n# after\nfrom binascii import unhexlify\nlib.unique_id_from_bytes(unhexlify(uid_hex))  # 128 bytes","handlingStrategy":"validation","validationCode":"assert isinstance(data, (bytes, bytearray)) and len(data) == 128, (\n    f\"ncclUniqueId payload must be exactly 128 raw bytes, got {type(data).__name__} len={len(data) if isinstance(data, (bytes, bytearray)) else 'n/a'}\")","typeGuard":"def is_valid_nccl_unique_id_bytes(data: object) -> bool:\n    return isinstance(data, (bytes, bytearray)) and len(data) == 128","tryCatchPattern":null,"preventionTips":["Serialize ids as bytes(unique_id.internal), never str/hex/list","Use one encode/decode helper for id transport across ranks","Add a round-trip unit test for id serialization"],"tags":["nccl","serialization","distributed","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}