{"record":{"id":"9bd81fa5e4557584","repo":"sgl-project/sglang","slug":"field-name-must-be-comparator-got-parsed","errorCode":null,"errorMessage":"{field_name} must be {comparator}, got {parsed}.","messagePattern":"(.+?) must be (.+?), got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/speculative/dflash_utils.py","lineNumber":522,"sourceCode":"    )\n    return sample_from_anchor is False\n\n\ndef _parse_optional_int(\n    value: Any,\n    *,\n    field_name: str,\n    min_value: Optional[int] = None,\n) -> Optional[int]:\n    if value is None:\n        return None\n    try:\n        parsed = int(value)\n    except Exception as e:\n        raise ValueError(f\"Invalid {field_name}={value!r}.\") from e\n    if min_value is not None and parsed < int(min_value):\n        comparator = \"positive\" if int(min_value) == 1 else f\">= {int(min_value)}\"\n        raise ValueError(f\"{field_name} must be {comparator}, got {parsed}.\")\n    return parsed\n\n\n@dataclass(frozen=True)\nclass DFlashDraftConfig:\n    num_hidden_layers: Optional[int]\n    num_target_layers: Optional[int]\n    block_size: Optional[int]\n    conv_kernel_size: int\n    conv_group_size: int\n    selector_rank: int\n    selector_top_k: int\n    output_multiplier: float\n    final_logit_softcapping: Optional[float]\n    target_layer_ids: Optional[List[int]]\n    mask_token: str\n    mask_token_id: Optional[int]\n","sourceCodeStart":504,"sourceCodeEnd":540,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/speculative/dflash_utils.py#L504-L540","documentation":"Raised by _parse_optional_int when a numeric field parses successfully but violates its minimum, e.g. a count field set to 0 or negative when min_value=1. The message names the field, the required bound (\"positive\" or \">= N\"), and the parsed value, so it pinpoints the bad entry in the DFLASH draft config.","triggerScenarios":"parse_dflash_draft_config with a field like topk/k compile to 0 when min_value >= 1, or a threshold set below its floor; parsed < int(min_value) triggers the raise.","commonSituations":"Draft config JSON sets a count to 0 thinking it disables the feature (use null instead); negative values from env overrides; copying a draft config from a different DFlash version with different minimums.","solutions":["Raise the field's value to at least the stated minimum (usually >= 1), or set it to null to use the default.","Check the DFlash draft config spec/docs for that field's allowed range.","If you intended to disable a feature, remove the field or set null rather than 0."],"exampleFix":"# before\n{\"speculative_eagle_topk\": 0}\n# after\n{\"speculative_eagle_topk\": 1}","handlingStrategy":"validation","validationCode":"FIELD_MIN = {'speculative_num_draft_tokens': 1, 'speculative_eagle_topk': 1}\nfor k, lo in FIELD_MIN.items():\n    v = draft_cfg.get(k)\n    if v is not None and int(v) < lo:\n        raise ValueError(f'{k} must be >= {lo}, got {v}')","typeGuard":"def within_min(v, lo: int) -> bool:\n    return v is None or (isinstance(v, int) and v >= lo)","tryCatchPattern":null,"preventionTips":["Use null/omit to disable optional numeric fields, never 0.","Document each draft-config field's minimum next to its definition."],"tags":["speculative-decoding","dflash","config-validation","range-check"],"backgroundTag":"config-value-out-of-range","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}