sgl-project/sglang · error · ValueError

kv-canary: pool_slot_count must be positive, got {pool_slot_

Error message

kv-canary: pool_slot_count must be positive, got {pool_slot_count}

What it means

from_args requires pool_slot_count > 0: the KV pool must have at least one slot for the canary to write/verify against. Zero or negative slots indicate a degenerate or misconfigured KV cache pool, and the canary refuses to install.

Source

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

    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}"
            )
        if pool_slot_count <= 0:
            raise ValueError(
                f"kv-canary: pool_slot_count must be positive, got {pool_slot_count}"
            )

        cuda_graph_config = get_exec().graph.cuda_graph_config
        cuda_graph_max_bs = (
            cuda_graph_config.decode.max_bs if cuda_graph_config is not None else 0
        ) or 0
        if cuda_graph_max_bs < 0:
            raise ValueError(
                f"kv-canary: cuda_graph_max_bs must be non-negative, got {cuda_graph_max_bs}"
            )

        spec_num_draft_tokens = get_spec().speculative_num_draft_tokens
        if spec_num_draft_tokens is None:
            spec_num_draft_tokens = 0
        if spec_num_draft_tokens < 0:
            raise ValueError(
                "kv-canary: speculative_num_draft_tokens must be non-negative, "

View on GitHub (pinned to 0132848349)

Solutions

1. Give the KV pool a positive size: raise --mem-fraction-static / remove --max-total-tokens 0
2. Check server startup logs that the KV pool actually allocated slots
3. Run with --kv-canary none if canary monitoring is not needed

Example fix

# before
--max-total-tokens 0 --kv-canary raise

# after
--max-total-tokens 16384 --kv-canary raise

if pool_slot_count <= 0:
    raise SystemExit("KV pool has no slots; raise --mem-fraction-static or unset --max-total-tokens")
caps = CanaryLaunchCapacities.from_args(pool_slot_count=pool_slot_count, ...)

def has_kv_slots(n: int) -> bool:
    return isinstance(n, int) and n > 0

When it happens

Trigger: Calling install_canary/from_args with pool_slot_count <= 0, e.g. when the KV cache pool sizing computed zero tokens/slots from --max-total-tokens 0, --kv-cache-dtype issues, or gpu-memory-utilization so low no cache fits.

Common situations: Starting with --max-total-tokens 0 or an extremely low --mem-fraction-static/--gpu-memory-utilization so the token pool is empty; overriding pool size in test harnesses with 0.

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: {name} must be positive, got {value}
• 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: 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/84eb42077f77a564. Report an issue: GitHub.