sgl-project/sglang · error · ValueError

LogicalHostPool size must be page-aligned, got size={size},

Error message

LogicalHostPool size must be page-aligned, got size={size}, page_size={page_size}

What it means

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.

Source

Thrown at python/sglang/srt/mem_cache/memory_pool_host.py:61

from sglang.srt.mem_cache.pool_host.common import (
    ALLOC_MEMORY_FUNCS,
    get_allocator_from_storage,
)
from sglang.srt.mem_cache.pool_host.hisparse import HiSparseHostPoolMixin

# ---- V4 Compressed KV Host Pools ----


class LogicalHostPool:
    """Pure-logical anchor pool for V4 HiCache.

    The pool manages page-aligned token slots but holds no KV tensor. V4
    compressed side pools use these logical FULL indices as stable page anchors.
    """

    def __init__(self, size: int, page_size: int, layout: str = "layer_first"):
        if size % page_size != 0:
            raise ValueError(
                "LogicalHostPool size must be page-aligned, "
                f"got size={size}, page_size={page_size}"
            )
        self.size = size
        # Stands in for a host pool (and group anchor); DCP never widens it.
        self.logical_size = size
        self.page_size = page_size
        self.device = "cpu"
        self.layout = layout
        self.dtype = torch.uint8
        self.layer_num = 0
        self.start_layer = 0
        self.end_layer = 0
        self.kv_buffer = None
        self.size_per_token = 0
        self.allocator = None
        self.can_use_write_back_jit = True
        self.lock = threading.RLock()

View on GitHub (pinned to 0132848349)

Solutions

1. Round the size down to the nearest page multiple before constructing: size = size // page_size * page_size
2. Check the page_size being passed (from server args / config) matches what the size was computed against
3. Add an assertion/log upstream where the size is derived so misalignment is caught earlier

Example fix

# before
pool = LogicalHostPool(size=num_tokens, page_size=page_size)

# after
size = (num_tokens // page_size) * page_size
pool = LogicalHostPool(size=size, page_size=page_size)

assert size % page_size == 0, f"size {size} not aligned to page {page_size}"

null

try:
    pool = LogicalHostPool(size, page_size)
except ValueError as e:
    size = (size // page_size) * page_size
    pool = LogicalHostPool(size, page_size)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• LogicalHostPool allocation must be page-aligned, got need_si
• v_cache must be provided
• q can only be None when only_qv=True
• q must be provided unless qv is provided with only_qv=True
• name must be provided

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/6ef8b5af808a07b7. Report an issue: GitHub.