{"record":{"id":"bab018a5f545822c","repo":"sgl-project/sglang","slug":"kv-canary-name-must-be-positive-got-value","errorCode":null,"errorMessage":"kv-canary: {name} must be positive, got {value}","messagePattern":"kv-canary: (.+?) must be positive, got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/kv_canary/capacities.py","lineNumber":42,"sourceCode":"            and the verify kernel skips the step; host logs a warn (no install-time raise).\n        per_forward_write_req_capacity: WritePlan row capacity for per-forward writes, also used\n            to size the static PlanInput buffers (= max batch size under cuda graph).\n        per_forward_write_entry_capacity: Capacity for the expected_input_* placeholder tensors,\n            one entry per token written in a single forward.\n    \"\"\"\n\n    per_forward_verify_capacity: int\n    per_forward_write_req_capacity: int\n    per_forward_write_entry_capacity: int\n\n    def __post_init__(self) -> None:\n        for name, value in (\n            (\"per_forward_verify_capacity\", self.per_forward_verify_capacity),\n            (\"per_forward_write_req_capacity\", self.per_forward_write_req_capacity),\n            (\"per_forward_write_entry_capacity\", self.per_forward_write_entry_capacity),\n        ):\n            if value <= 0:\n                raise ValueError(f\"kv-canary: {name} must be positive, got {value}\")\n\n    @classmethod\n    def from_args(\n        cls,\n        *,\n        req_to_token_pool_size: int,\n        max_seq_len_per_req: int,\n        pool_slot_count: int,\n    ) -> CanaryLaunchCapacities:\n        if req_to_token_pool_size <= 0:\n            raise ValueError(\n                \"kv-canary: req_to_token_pool_size must be positive, \"\n                f\"got {req_to_token_pool_size}\"\n            )\n        if max_seq_len_per_req <= 0:\n            raise ValueError(\n                \"kv-canary: max_seq_len_per_req must be positive, \"\n                f\"got {max_seq_len_per_req}\"","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/kv_canary/capacities.py#L24-L60","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure all three per_forward capacity fields are >= 1 when constructing CanaryLaunchCapacities","Prefer disabling the canary with --kv-canary none rather than zeroing capacities","Check upstream args (req pool size, spec config) that feed the capacity computation so derived values stay positive"],"exampleFix":"# before\nCanaryLaunchCapacities(..., per_forward_verify_capacity=0, ...)\n\n# after\nCanaryLaunchCapacities(..., per_forward_verify_capacity=8, ...)","handlingStrategy":"validation","validationCode":"caps = dict(\n    per_forward_verify_capacity=8,\n    per_forward_write_req_capacity=4,\n    per_forward_write_entry_capacity=16,\n)\nassert all(v > 0 for v in caps.values()), f\"capacities must be positive: {caps}\"\nobj = CanaryLaunchCapacities(**caps)","typeGuard":"def has_positive_per_forward_caps(c) -> bool:\n    return all([\n        c.per_forward_verify_capacity > 0,\n        c.per_forward_write_req_capacity > 0,\n        c.per_forward_write_entry_capacity > 0,\n    ])","tryCatchPattern":null,"preventionTips":["Never pass 0 to 'disable' a canary capacity; use --kv-canary none","Clamp derived capacities to at least 1 before constructing the dataclass","Unit-test config builders with boundary values (0, negative)"],"tags":["kv-canary","validation","capacities","value-error"],"backgroundTag":"config-validation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}