sgl-project/sglang · error · ValueError

kv-canary: {name} must be positive, got {value}

Error message

kv-canary: {name} must be positive, got {value}

What it means

CanaryLaunchCapacities validates its per-forward capacity fields in __post_init__ and requires all three (per_forward_verify_capacity, per_forward_write_req_capacity, per_forward_write_entry_capacity) to be strictly positive. These sizes size the per-forward canary buffers, so zero or negative values would make the canary unable to track anything. A ValueError naming the offending field is raised.

Source

Thrown at python/sglang/srt/kv_canary/capacities.py:42

            and the verify kernel skips the step; host logs a warn (no install-time raise).
        per_forward_write_req_capacity: WritePlan row capacity for per-forward writes, also used
            to size the static PlanInput buffers (= max batch size under cuda graph).
        per_forward_write_entry_capacity: Capacity for the expected_input_* placeholder tensors,
            one entry per token written in a single forward.
    """

    per_forward_verify_capacity: int
    per_forward_write_req_capacity: int
    per_forward_write_entry_capacity: int

    def __post_init__(self) -> None:
        for name, value in (
            ("per_forward_verify_capacity", self.per_forward_verify_capacity),
            ("per_forward_write_req_capacity", self.per_forward_write_req_capacity),
            ("per_forward_write_entry_capacity", self.per_forward_write_entry_capacity),
        ):
            if value <= 0:
                raise ValueError(f"kv-canary: {name} must be positive, got {value}")

    @classmethod
    def from_args(
        cls,
        *,
        req_to_token_pool_size: int,
        max_seq_len_per_req: int,
        pool_slot_count: int,
    ) -> CanaryLaunchCapacities:
        if req_to_token_pool_size <= 0:
            raise ValueError(
                "kv-canary: req_to_token_pool_size must be positive, "
                f"got {req_to_token_pool_size}"
            )
        if max_seq_len_per_req <= 0:
            raise ValueError(
                "kv-canary: max_seq_len_per_req must be positive, "
                f"got {max_seq_len_per_req}"

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure all three per_forward capacity fields are >= 1 when constructing CanaryLaunchCapacities
2. Prefer disabling the canary with --kv-canary none rather than zeroing capacities
3. Check upstream args (req pool size, spec config) that feed the capacity computation so derived values stay positive

Example fix

# before
CanaryLaunchCapacities(..., per_forward_verify_capacity=0, ...)

# after
CanaryLaunchCapacities(..., per_forward_verify_capacity=8, ...)

caps = dict(
    per_forward_verify_capacity=8,
    per_forward_write_req_capacity=4,
    per_forward_write_entry_capacity=16,
)
assert all(v > 0 for v in caps.values()), f"capacities must be positive: {caps}"
obj = CanaryLaunchCapacities(**caps)

def has_positive_per_forward_caps(c) -> bool:
    return all([
        c.per_forward_verify_capacity > 0,
        c.per_forward_write_req_capacity > 0,
        c.per_forward_write_entry_capacity > 0,
    ])

When it happens

Trigger: Constructing CanaryLaunchCapacities (directly or via from_args) with any of the three per_forward capacity fields <= 0, e.g. passing computed capacities of 0 because an upstream config (max running requests, draft tokens) degenerated to zero.

Common situations: Misconfigured kv-canary launch where derived request/entry counts round down to zero; explicitly setting capacity kwargs to 0 to 'disable' one canary path instead of disabling the canary via --kv-canary none.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• kv-canary: req_to_token_pool_size must be positive, got {req
• kv-canary: max_seq_len_per_req must be positive, got {max_se
• kv-canary: pool_slot_count must be positive, got {pool_slot_
• kv-canary: cuda_graph_max_bs must be non-negative, got {cuda
• kv-canary: speculative_num_draft_tokens must be non-negative

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