sgl-project/sglang · error · ValueError

beam_width must be at least 1, got {self.beam_width}.

Error message

beam_width must be at least 1, got {self.beam_width}.

What it means

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).

Source

Thrown at python/sglang/srt/sampling/sampling_params.py:156

        )

        # An empty grammar constraint means "unset", not "constrain to nothing".
        self.json_schema = self.json_schema or None
        self.regex = self.regex or None
        self.ebnf = self.ebnf or None
        self.structural_tag = self.structural_tag or None

        # Process some special cases
        if 0 <= self.temperature < _SAMPLING_EPS:
            # top_k = 1 means greedy sampling
            self.temperature = 1.0
            self.top_k = 1
        if self.top_k == -1:
            self.top_k = TOP_K_ALL  # whole vocabulary

    def verify(self, vocab_size):
        if self.beam_width is not None and self.beam_width < 1:
            raise ValueError(f"beam_width must be at least 1, got {self.beam_width}.")
        if not math.isfinite(self.temperature) or self.temperature < 0.0:
            raise ValueError(
                f"temperature must be a non-negative finite number, got {self.temperature}."
            )
        if not 0.0 < self.top_p <= 1.0:
            raise ValueError(f"top_p must be in (0, 1], got {self.top_p}.")
        if not 0.0 <= self.min_p <= 1.0:
            raise ValueError(f"min_p must be in [0, 1], got {self.min_p}.")
        if self.top_k < 1 or self.top_k == -1:
            raise ValueError(
                f"top_k must be -1 (disable) or at least 1, got {self.top_k}."
            )
        if not -2.0 <= self.frequency_penalty <= 2.0:
            raise ValueError(
                "frequency_penalty must be in [-2, 2], got "
                f"{self.frequency_penalty}."
            )
        if not -2.0 <= self.presence_penalty <= 2.0:

View on GitHub (pinned to 0132848349)

Solutions

  1. Set beam_width=None (or omit it) unless you specifically want beam search
  2. Set beam_width to an integer >= 1, e.g. beam_width=4, when beam search is intended
  3. Validate beam_width in your own config layer before passing it to SGLang

Example fix

// before
params = SamplingParams(beam_width=0)
// after
params = SamplingParams(beam_width=None)  # or beam_width=4 for beam search
Defensive patterns

Strategy: validation

Validate before calling

if beam_width is not None and beam_width < 1:
    beam_width = None
params = SamplingParams(beam_width=beam_width)

Type guard

def valid_beam_width(bw):
    return bw is None or (isinstance(bw, int) and bw >= 1)

Try / catch

try:
    out = llm.generate(prompts, SamplingParams(beam_width=bw))
except ValueError as e:
    if 'beam_width' in str(e):
        bw = None  # retry without beam search
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/2ebedb1713f7600f. Report an issue: GitHub.