sgl-project/sglang · error · ValueError

For classifier-free guidance, either `negative_prompt` or `n

Error message

For classifier-free guidance, either `negative_prompt` or `negative_prompt_embeds` must be provided

What it means

When classifier-free guidance is enabled (do_classifier_free_guidance=True), the pipeline needs either negative_prompt or negative_prompt_embeds to build the unconditional branch. If both are None, CFG cannot be computed and validation fails fast.

Source

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

            batch.num_inference_steps = (
                server_args.pipeline_config.shape_num_inference_steps
            )

        # Ensure prompt is properly formatted (I2M can be image-only)
        if (
            server_args.pipeline_config.task_type != ModelTaskType.I2M
            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,

View on GitHub (pinned to 0132848349)

Solutions

  1. Send a negative_prompt (an empty string "" usually suffices) in each request when using CFG
  2. Or supply negative_prompt_embeds if you precompute embeddings
  3. If you do not want CFG, disable it so do_classifier_free_guidance is False (guidance_scale <= 1 or the server-side CFG flag off)

Example fix

// before
out = pipe(prompt="a cat", guidance_scale=7.5)

// after
out = pipe(prompt="a cat", negative_prompt="", guidance_scale=7.5)
Defensive patterns

Strategy: validation

Validate before calling

if batch.do_classifier_free_guidance:
    assert batch.negative_prompt is not None or batch.negative_prompt_embeds is not None, \
        "CFG requires negative_prompt (empty string is fine)"

Type guard

def cfg_inputs_valid(batch) -> bool:
    return not batch.do_classifier_free_guidance or batch.negative_prompt is not None or batch.negative_prompt_embeds is not None

Prevention

When it happens

Trigger: Enabling CFG (guidance_scale > 1 / cfg flags) but submitting requests with no negative_prompt field and no negative_prompt_embeds, or a server default that enables CFG while the client omits negative prompts.

Common situations: Clients that never send negative_prompt against a CFG-enabled server; toggling --disable-cfg or cfg-parallel flags so do_classifier_free_guidance flips true unexpectedly; programmatic batch construction omitting the negative fields.

Related errors

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