sgl-project/sglang · error · ValueError

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

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.

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

• BatchedDecodeContext requires full_kv_pool_index_by_layer…
• Page size mismatch: prefill server has page_size=
• realtime_causal_kv_cache_num_frames must be positive
• realtime_causal_sink_size must be non-negative
• SGLANG_DISAGG_STAGING_BUFFER requires a positive…

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

Appendix: 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)