{"record":{"id":"6ef8b5af808a07b7","repo":"sgl-project/sglang","slug":"logicalhostpool-size-must-be-page-aligned-got-siz","errorCode":null,"errorMessage":"LogicalHostPool size must be page-aligned, got size={size}, page_size={page_size}","messagePattern":"LogicalHostPool size must be page-aligned, got size=(.+?), page_size=(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/memory_pool_host.py","lineNumber":61,"sourceCode":"from sglang.srt.mem_cache.pool_host.common import (\n    ALLOC_MEMORY_FUNCS,\n    get_allocator_from_storage,\n)\nfrom sglang.srt.mem_cache.pool_host.hisparse import HiSparseHostPoolMixin\n\n# ---- V4 Compressed KV Host Pools ----\n\n\nclass LogicalHostPool:\n    \"\"\"Pure-logical anchor pool for V4 HiCache.\n\n    The pool manages page-aligned token slots but holds no KV tensor. V4\n    compressed side pools use these logical FULL indices as stable page anchors.\n    \"\"\"\n\n    def __init__(self, size: int, page_size: int, layout: str = \"layer_first\"):\n        if size % page_size != 0:\n            raise ValueError(\n                \"LogicalHostPool size must be page-aligned, \"\n                f\"got size={size}, page_size={page_size}\"\n            )\n        self.size = size\n        # Stands in for a host pool (and group anchor); DCP never widens it.\n        self.logical_size = size\n        self.page_size = page_size\n        self.device = \"cpu\"\n        self.layout = layout\n        self.dtype = torch.uint8\n        self.layer_num = 0\n        self.start_layer = 0\n        self.end_layer = 0\n        self.kv_buffer = None\n        self.size_per_token = 0\n        self.allocator = None\n        self.can_use_write_back_jit = True\n        self.lock = threading.RLock()","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/memory_pool_host.py#L43-L79","documentation":"LogicalHostPool, a page-tracking host pool that holds no KV tensor, requires its total slot count to be a multiple of page_size. __init__ raises ValueError when size % page_size != 0 because all allocation bookkeeping is done in whole pages.","triggerScenarios":"Constructing LogicalHostPool(size=N, page_size=P) where N is not divisible by P; e.g. LogicalHostPool(1000, 16) with a host-page budget derived from raw token counts without rounding down to page multiples.","commonSituations":"Custom host-memory sizing scripts or configs that compute host pool size as token counts (e.g. bytes/token math) and forget to align to the configured page size; changing --page-size after computing host capacity.","solutions":["Round the size down to the nearest page multiple before constructing: size = size // page_size * page_size","Check the page_size being passed (from server args / config) matches what the size was computed against","Add an assertion/log upstream where the size is derived so misalignment is caught earlier"],"exampleFix":"# before\npool = LogicalHostPool(size=num_tokens, page_size=page_size)\n\n# after\nsize = (num_tokens // page_size) * page_size\npool = LogicalHostPool(size=size, page_size=page_size)","handlingStrategy":"validation","validationCode":"assert size % page_size == 0, f\"size {size} not aligned to page {page_size}\"","typeGuard":"null","tryCatchPattern":"try:\n    pool = LogicalHostPool(size, page_size)\nexcept ValueError as e:\n    size = (size // page_size) * page_size\n    pool = LogicalHostPool(size, page_size)","preventionTips":["Always derive pool sizes via floor-division by page_size","Log size, page_size and their remainder at construction","Keep one source of truth for page_size across config and pool construction"],"tags":["sglang","memory-pool","page-alignment","validation"],"backgroundTag":"page-alignment-validation","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}