sgl-project/sglang · error · ValueError

Number of inference steps must be positive, but got {batch.n

Error message

Number of inference steps must be positive, but got {batch.num_inference_steps}

What it means

num_inference_steps must be a positive integer (>= 1). The validation stage rejects requests with 0 or negative steps because the denoising loop would never execute or is meaningless.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/input_validation.py:340

            and batch.prompt is None
            and batch.prompt_embeds is None
        ):
            raise ValueError("Either `prompt` or `prompt_embeds` must be provided")

        # Ensure negative prompt is properly formatted if using classifier-free guidance
        if (
            batch.do_classifier_free_guidance
            and batch.negative_prompt is None
            and batch.negative_prompt_embeds is None
        ):
            raise ValueError(
                "For classifier-free guidance, either `negative_prompt` or "
                "`negative_prompt_embeds` must be provided"
            )

        # Validate number of inference steps
        if batch.num_inference_steps <= 0:
            raise ValueError(
                f"Number of inference steps must be positive, but got {batch.num_inference_steps}"
            )

        # Validate guidance scale if using classifier-free guidance
        if batch.do_classifier_free_guidance and batch.guidance_scale < 0:
            raise ValueError(
                f"Guidance scale must be positive, but got {batch.guidance_scale}"
            )

        # Reject requests that do not enable CFG on a server launched with
        # --enable-cfg-parallel. CFG-parallel splits cond/uncond across ranks,
        # so rank 1 has no work and returns None for noise_pred, which crashes
        # scheduler.step() ~30 minutes later under a gloo broadcast timeout.
        # Earlier, field-specific checks above (negative_prompt missing,
        # guidance_scale < 0) fire first and produce better messages for those
        # cases; this is the catch-all for any combination that still leaves
        # do_classifier_free_guidance=False under cfg-parallel.
        if server_args.enable_cfg_parallel and not batch.do_classifier_free_guidance:

View on GitHub (pinned to 0132848349)

Solutions

1. Set num_inference_steps to at least 1 (typically 20-50 for standard, 4-8 for distilled models)
2. Check any computed step counts (e.g. steps*strength roundings) and clamp with max(1, ...)
3. Verify request serialization is not turning a missing field into 0

Example fix

// before
out = pipe(prompt="a cat", num_inference_steps=0)

// after
out = pipe(prompt="a cat", num_inference_steps=max(1, num_inference_steps))

batch.num_inference_steps = max(1, int(batch.num_inference_steps))
assert batch.num_inference_steps > 0

def valid_step_count(n) -> bool:
    return isinstance(n, int) and n >= 1

When it happens

Trigger: Passing num_inference_steps=0, a negative value, or a config/env default that resolves to 0 (e.g. unset strength/distillation settings collapsing steps to 0).

Common situations: Distilled-model configs where steps is computed from guidance/distillation parameters and underflows to 0; clients sending num_inference_steps from an unset optional field defaulting to 0; arithmetic like int(steps * strength) with tiny strength.

Related errors

• Guidance scale must be positive, but got {batch.guidance_sca
• unsupported input for causal Conv3D cat/pad CUDA
• unsupported input for usp_merge_heads CUDA
• unsupported input for modulate_scale_shift CUDA
• unsupported input for LTX2 QKNorm split-RoPE CUDA

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