{"record":{"id":"3c1f85b48b0b9782","repo":"sgl-project/sglang","slug":"guidance-scale-must-be-positive-but-got-batch-gu","errorCode":null,"errorMessage":"Guidance scale must be positive, but got {batch.guidance_scale}","messagePattern":"Guidance scale must be positive, but got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/input_validation.py","lineNumber":346,"sourceCode":"        if (\n            batch.do_classifier_free_guidance\n            and batch.negative_prompt is None\n            and batch.negative_prompt_embeds is None\n        ):\n            raise ValueError(\n                \"For classifier-free guidance, either `negative_prompt` or \"\n                \"`negative_prompt_embeds` must be provided\"\n            )\n\n        # Validate number of inference steps\n        if batch.num_inference_steps <= 0:\n            raise ValueError(\n                f\"Number of inference steps must be positive, but got {batch.num_inference_steps}\"\n            )\n\n        # Validate guidance scale if using classifier-free guidance\n        if batch.do_classifier_free_guidance and batch.guidance_scale < 0:\n            raise ValueError(\n                f\"Guidance scale must be positive, but got {batch.guidance_scale}\"\n            )\n\n        # Reject requests that do not enable CFG on a server launched with\n        # --enable-cfg-parallel. CFG-parallel splits cond/uncond across ranks,\n        # so rank 1 has no work and returns None for noise_pred, which crashes\n        # scheduler.step() ~30 minutes later under a gloo broadcast timeout.\n        # Earlier, field-specific checks above (negative_prompt missing,\n        # guidance_scale < 0) fire first and produce better messages for those\n        # cases; this is the catch-all for any combination that still leaves\n        # do_classifier_free_guidance=False under cfg-parallel.\n        if server_args.enable_cfg_parallel and not batch.do_classifier_free_guidance:\n            neg_prompt_state = (\n                \"not set\"\n                if batch.negative_prompt is None\n                else \"empty\" if batch.negative_prompt == \"\" else \"set\"\n            )\n            raise ValueError(","sourceCodeStart":328,"sourceCodeEnd":364,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/input_validation.py#L328-L364","documentation":"When CFG is active, guidance_scale must be non-negative (the check rejects values < 0). A negative guidance scale would push samples away from the prompt in an unsupported way, so validation fails before any denoising step runs.","triggerScenarios":"Passing a negative guidance_scale (e.g. -7.5) together with do_classifier_free_guidance=True, or a request builder that negates/mis-parses the scale field.","commonSituations":"Typos/sign errors in client configs; JSON configs where guidance_scale is read as a negative number; experiments with 'negative guidance' not supported by this pipeline; note the check allows 0 (which effectively disables CFG weighting) but not below.","solutions":["Use a non-negative guidance_scale (0 to ~15; 7.5 is a common default)","If you intended to disable CFG, set guidance_scale=0 or turn off do_classifier_free_guidance rather than negating it","Sanity-check parsed config values before submitting"],"exampleFix":"// before\nout = pipe(prompt=\"a cat\", guidance_scale=-7.5)\n\n// after\nout = pipe(prompt=\"a cat\", guidance_scale=7.5)","handlingStrategy":"validation","validationCode":"if batch.do_classifier_free_guidance:\n    batch.guidance_scale = abs(float(batch.guidance_scale))\n    assert batch.guidance_scale >= 0","typeGuard":"def valid_guidance_scale(scale, cfg: bool) -> bool:\n    return not cfg or scale >= 0","tryCatchPattern":null,"preventionTips":["Validate guidance_scale range (0-15) client-side","Avoid sign manipulations of guidance values; use CFG toggles instead"],"tags":["cfg","guidance-scale","input-validation","range-check"],"backgroundTag":"out-of-range-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}