sgl-project/sglang · error · ValueError

kv-canary: max_seq_len_per_req must be positive, got {max_se

Error message

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

What it means

from_args requires max_seq_len_per_req > 0 because the canary needs at least one token slot per request to compute write/verify capacities. A non-positive max sequence length makes per-request capacity math meaningless, so ValueError is raised at canary installation time.

Source

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

        ):
            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}"
            )
        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

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure max_seq_len_per_req is >= 1 (check --context-length and memory-related flags)
2. Remove flags that force the derived max sequence length to zero
3. Disable the canary with --kv-canary none if it is not needed

Example fix

# before
--context-length 0 --kv-canary log

# after
--context-length 8192 --kv-canary log

if max_seq_len_per_req <= 0:
    raise SystemExit("max_seq_len_per_req must be > 0; check --context-length")
caps = CanaryLaunchCapacities.from_args(
    max_seq_len_per_req=max_seq_len_per_req, ...
)

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

When it happens

Trigger: Calling install_canary/from_args with max_seq_len_per_req <= 0, e.g. server started with --max-total-tokens or context-length flags that collapse max_seq_len_per_req to 0.

Common situations: Over-restrictive memory flags (--max-total-tokens 0, tiny context length) combined with --kv-canary; miscomputed derived context length in custom launch scripts.

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: 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/7d169ee1459a0280. Report an issue: GitHub.