{"record":{"id":"822c4b6e65ea3139","repo":"sgl-project/sglang","slug":"kv-canary-max-prefill-tokens-must-be-positive-go","errorCode":null,"errorMessage":"kv-canary: max_prefill_tokens must be positive, got {max_prefill_tokens}","messagePattern":"kv-canary: max_prefill_tokens must be positive, got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/kv_canary/capacities.py","lineNumber":87,"sourceCode":"            cuda_graph_config.decode.max_bs if cuda_graph_config is not None else 0\n        ) or 0\n        if cuda_graph_max_bs < 0:\n            raise ValueError(\n                f\"kv-canary: cuda_graph_max_bs must be non-negative, got {cuda_graph_max_bs}\"\n            )\n\n        spec_num_draft_tokens = get_spec().speculative_num_draft_tokens\n        if spec_num_draft_tokens is None:\n            spec_num_draft_tokens = 0\n        if spec_num_draft_tokens < 0:\n            raise ValueError(\n                \"kv-canary: speculative_num_draft_tokens must be non-negative, \"\n                f\"got {spec_num_draft_tokens}\"\n            )\n\n        max_prefill_tokens = get_schedule().max_prefill_tokens\n        if max_prefill_tokens <= 0:\n            raise ValueError(\n                f\"kv-canary: max_prefill_tokens must be positive, got {max_prefill_tokens}\"\n            )\n\n        num_tokens_per_req = 1\n        if spec_num_draft_tokens:\n            num_tokens_per_req = max(num_tokens_per_req, spec_num_draft_tokens)\n\n        max_bs = max(cuda_graph_max_bs, req_to_token_pool_size)\n\n        chunked_prefill_size = get_schedule().chunked_prefill_size\n        chunked_limit = (\n            chunked_prefill_size\n            if chunked_prefill_size is not None and chunked_prefill_size >= 0\n            else math.inf\n        )\n        max_extend_tokens_per_forward = min(max_prefill_tokens, chunked_limit)\n\n        write_entry_capacity = max(","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/kv_canary/capacities.py#L69-L105","documentation":"from_args requires the scheduler's max_prefill_tokens to be strictly positive because the canary sizes its per-forward buffers from the prefill token budget. A zero or negative prefill budget means no prefill batch can ever run, so the canary refuses to install.","triggerScenarios":"Calling install_canary/from_args with --max-prefill-tokens 0 or negative, or a scheduler config where max_prefill_tokens was overridden/computed to <= 0.","commonSituations":"Explicitly setting --max-prefill-tokens 0 in benchmarking or memory-constrained setups and forgetting to disable --kv-canary; derived configs in test harnesses that zero out scheduler budgets.","solutions":["Set --max-prefill-tokens to a positive value (e.g. 16384)","Remove the flag to use the default scheduler budget","Run with --kv-canary none if you intentionally want zero prefill budget"],"exampleFix":"# before\n--max-prefill-tokens 0 --kv-canary log\n\n# after\n--max-prefill-tokens 16384 --kv-canary log","handlingStrategy":"validation","validationCode":"if get_schedule().max_prefill_tokens <= 0:\n    raise SystemExit(\"max_prefill_tokens must be > 0; set --max-prefill-tokens 16384 or remove the flag\")\ncaps = CanaryLaunchCapacities.from_args(...)","typeGuard":"def valid_prefill_budget(n: int) -> bool:\n    return isinstance(n, int) and n > 0","tryCatchPattern":null,"preventionTips":["Keep --max-prefill-tokens positive when the canary is on","Omit the flag to use defaults instead of zeroing it","Audit benchmark scripts that zero scheduler budgets"],"tags":["kv-canary","validation","prefill","scheduler","value-error"],"backgroundTag":"config-validation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}