{"record":{"id":"50067e8e9866a1d9","repo":"vllm-project/vllm","slug":"hf3fsclient-check-failed","errorCode":null,"errorMessage":"Hf3fsClient.check Failed","messagePattern":"Hf3fsClient\\.check Failed","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_client.py","lineNumber":278,"sourceCode":"        results = [res.result for res in resv]\n\n        return results\n\n    def check(self, offsets: list[int], tensors: list[torch.Tensor]) -> None:\n        sizes = [t.numel() * t.itemsize for t in tensors]\n        if any(\n            [\n                len(offsets) > self.entries,\n                len(offsets) != len(sizes),\n                any(\n                    offset < 0 or offset + size > self.size\n                    for offset, size in zip(offsets, sizes)\n                ),\n                any(size > self.bytes_per_page for size in sizes),\n            ]\n        ):\n            self.close()\n            raise ValueError(\"Hf3fsClient.check Failed\")\n\n    def get_size(self) -> int:\n        \"\"\"Get the total size of the storage file.\n\n        Returns:\n            Size of the file in bytes\n        \"\"\"\n        return self.size\n\n    def close(self) -> None:\n        \"\"\"Close the client and clean up resources.\"\"\"\n        if self._closed:\n            return\n        self._closed = True\n        self._release_resources()\n\n    def flush(self) -> None:\n        \"\"\"Flush any pending writes to disk.\"\"\"","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/hf3fs/hf3fs_client.py#L260-L296","documentation":"Hf3fsClient.check validates a batch of (offset, size) I/O operations against the client's capacity: number of ops must not exceed 'entries', offsets and sizes arrays must be equal length, every [offset, offset+size) must fall inside the storage file of 'size' bytes, and each size must not exceed 'bytes_per_page'. Any violation closes the client and raises this ValueError.","triggerScenarios":"Calling the client's batch read/write with mismatched offsets/sizes lengths, more entries than the configured concurrency, an out-of-bounds offset/size, or a transfer larger than bytes_per_page.","commonSituations":"Page-size mismatch between the connector and the Hf3fsClient configuration (size > bytes_per_page); off-by-one or stale page indices producing out-of-range offsets; batching more requests than 'entries' allows.","solutions":["Ensure per-op size <= bytes_per_page and align the connector's page size with the client configuration","Validate len(offsets)==len(sizes) and len(offsets)<=entries before issuing the batch","Check that all offsets satisfy 0 <= offset and offset+size <= total size — stale/overflowing page indices are the usual culprit","After this error the client is closed; recreate the Hf3fsClient before retrying"],"exampleFix":"# before\nclient.write(offsets=[p * page for p in pages], sizes=[page * 2])  # size > bytes_per_page\n\n# after\nassert all(0 <= o and o + s <= client.size for o, s in zip(offsets, sizes))\nassert all(s <= client.bytes_per_page for s in sizes)\nassert len(offsets) <= client.entries and len(offsets) == len(sizes)\nclient.write(offsets=offsets, sizes=sizes)","handlingStrategy":"validation","validationCode":"def valid_batch(client, offsets, sizes):\n    return (\n        len(offsets) == len(sizes)\n        and len(offsets) <= client.entries\n        and all(0 <= o and o + s <= client.size for o, s in zip(offsets, sizes))\n        and all(s <= client.bytes_per_page for s in sizes)\n    )","typeGuard":null,"tryCatchPattern":"try:\n    client.write(offsets=offsets, sizes=sizes)\nexcept ValueError as e:\n    if 'Hf3fsClient.check Failed' in str(e):\n        client = Hf3fsClient(path, size, bytes_per_page, entries)  # client closed on failure\n        raise  # re-report after recreating\n    raise","preventionTips":["Align connector page size with bytes_per_page at configuration time","Always validate offset/size batches before I/O","Remember the client closes itself on this error — recreate before retry"],"tags":["kv-transfer","hf3fs","validation","bounds-check","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}