sgl-project/sglang · error · ValueError

kv-canary: RealKvSource.page_size must be >= 1, got {self.pa

Error message

kv-canary: RealKvSource.page_size must be >= 1, got {self.page_size}

What it means

RealKvSource is a frozen dataclass describing one piece of real KV memory the canary fingerprints; __post_init__ validates page_size >= 1 because it is used to convert token positions into page indices. Zero or negative page sizes would produce garbage indices, so ValueError is raised at construction.

Source

Thrown at python/sglang/kernels/ops/kv_canary/verify.py:95

    Fields:
        tensor: The source tensor, any shape such that the access pattern above yields ``num_bytes_per_token``
            uint8 bytes per slot. Dtype is whatever the underlying pool uses; the canary views the relevant
            bytes via ``.view(torch.uint8)``.
        page_size: Number of slots packed into one row of dim 0. ``>= 1``.
        num_bytes_per_token: Bytes per slot in the dim-1 strip the canary reads. Must be a positive
            multiple of 16.
        read_bytes: Leading bytes (out of ``num_bytes_per_token``) per slot folded into the fingerprint.
            Must be a positive multiple of 16, ``<= num_bytes_per_token``.
    """

    tensor: torch.Tensor
    page_size: int
    num_bytes_per_token: int
    read_bytes: int

    def __post_init__(self) -> None:
        if self.page_size < 1:
            raise ValueError(
                f"kv-canary: RealKvSource.page_size must be >= 1, got {self.page_size}"
            )
        if self.num_bytes_per_token <= 0 or self.num_bytes_per_token % 16 != 0:
            raise ValueError(
                f"kv-canary: RealKvSource.num_bytes_per_token must be a positive multiple of 16, "
                f"got {self.num_bytes_per_token}"
            )
        if (
            self.read_bytes <= 0
            or self.read_bytes > self.num_bytes_per_token
            or self.read_bytes % 16 != 0
        ):
            raise ValueError(
                f"kv-canary: RealKvSource.read_bytes must be a positive multiple of 16 in "
                f"(0, num_bytes_per_token={self.num_bytes_per_token}], got {self.read_bytes}"
            )
        if self.tensor.ndim < 2:
            raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

1. Pass the actual page size from the KV allocator / memory pool config
2. Guard configs: if page_size <= 0, raise or fix upstream before constructing the source

Example fix

# before
src = RealKvSource(page_size=0, ...)
# after
src = RealKvSource(page_size=pool.page_size, ...)

assert page_size >= 1, page_size

When it happens

Trigger: Constructing RealKvSource(page_size=0, ...) or with a negative value, e.g. reading page size from a config where 0 means 'unset'.

Common situations: Config plumbing where page_size defaults to 0 before the allocator initializes; deriving page size from a division that yielded 0.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• realtime_causal_sink_size must be non-negative
• realtime_causal_kv_cache_num_frames must be positive
• Page size mismatch: prefill server has page_size={info.page_
• SGLANG_DISAGG_STAGING_BUFFER requires a positive chunked_pre
• BatchedDecodeContext requires full_kv_pool_index_by_layer wh

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