{"record":{"id":"2ebedb1713f7600f","repo":"sgl-project/sglang","slug":"beam-width-must-be-at-least-1-got-self-beam-widt","errorCode":null,"errorMessage":"beam_width must be at least 1, got {self.beam_width}.","messagePattern":"beam_width must be at least 1, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/sampling/sampling_params.py","lineNumber":156,"sourceCode":"        )\n\n        # An empty grammar constraint means \"unset\", not \"constrain to nothing\".\n        self.json_schema = self.json_schema or None\n        self.regex = self.regex or None\n        self.ebnf = self.ebnf or None\n        self.structural_tag = self.structural_tag or None\n\n        # Process some special cases\n        if 0 <= self.temperature < _SAMPLING_EPS:\n            # top_k = 1 means greedy sampling\n            self.temperature = 1.0\n            self.top_k = 1\n        if self.top_k == -1:\n            self.top_k = TOP_K_ALL  # whole vocabulary\n\n    def verify(self, vocab_size):\n        if self.beam_width is not None and self.beam_width < 1:\n            raise ValueError(f\"beam_width must be at least 1, got {self.beam_width}.\")\n        if not math.isfinite(self.temperature) or self.temperature < 0.0:\n            raise ValueError(\n                f\"temperature must be a non-negative finite number, got {self.temperature}.\"\n            )\n        if not 0.0 < self.top_p <= 1.0:\n            raise ValueError(f\"top_p must be in (0, 1], got {self.top_p}.\")\n        if not 0.0 <= self.min_p <= 1.0:\n            raise ValueError(f\"min_p must be in [0, 1], got {self.min_p}.\")\n        if self.top_k < 1 or self.top_k == -1:\n            raise ValueError(\n                f\"top_k must be -1 (disable) or at least 1, got {self.top_k}.\"\n            )\n        if not -2.0 <= self.frequency_penalty <= 2.0:\n            raise ValueError(\n                \"frequency_penalty must be in [-2, 2], got \"\n                f\"{self.frequency_penalty}.\"\n            )\n        if not -2.0 <= self.presence_penalty <= 2.0:","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/sampling/sampling_params.py#L138-L174","documentation":"SamplingParams.verify() rejects a beam_width value below 1. SGLang validates sampling parameters when they are normalized before a request is scheduled, so any user-supplied beam_width of 0 or negative (or 0.0 as a float) raises this ValueError at request time. beam_width only activates speculative beam search, otherwise it must be left as None (default).","triggerScenarios":"Passing SamplingParams(beam_width=0) or a negative value (or a value coerced from 0 by config parsing) to the LLM/engine generate() API; verify() is invoked via normalize() during request preparation.","commonSituations":"Copying configs from other engines where beam_width=0 means 'disabled'; math on the config producing 0; JSON/YAML configs defaulting numeric fields to 0 instead of null.","solutions":["Set beam_width=None (or omit it) unless you specifically want beam search","Set beam_width to an integer >= 1, e.g. beam_width=4, when beam search is intended","Validate beam_width in your own config layer before passing it to SGLang"],"exampleFix":"// before\nparams = SamplingParams(beam_width=0)\n// after\nparams = SamplingParams(beam_width=None)  # or beam_width=4 for beam search","handlingStrategy":"validation","validationCode":"if beam_width is not None and beam_width < 1:\n    beam_width = None\nparams = SamplingParams(beam_width=beam_width)","typeGuard":"def valid_beam_width(bw):\n    return bw is None or (isinstance(bw, int) and bw >= 1)","tryCatchPattern":"try:\n    out = llm.generate(prompts, SamplingParams(beam_width=bw))\nexcept ValueError as e:\n    if 'beam_width' in str(e):\n        bw = None  # retry without beam search\n    else:\n        raise","preventionTips":["Treat None as the only 'disabled' value for beam_width","Validate numeric config fields before constructing SamplingParams"],"tags":["sampling-params","beam-search","validation","sglang"],"backgroundTag":"sampling-parameter-validation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}