sgl-project/sglang · error · ValueError

LTX2 stage-1 CFG parallel degree exceeds guidance pass count

Error message

LTX2 stage-1 CFG parallel degree exceeds guidance pass count.

What it means

When stage-1 CFG parallel is enabled, the base guidance pass specs are distributed across the SP/CFG-parallel degree; if the degree exceeds the number of guidance passes, no execution passes remain (empty list) and the model would be called with batch 0, so it raises.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/ltx_2/denoising.py:2204

                                audio_encoder_hidden_states=audio_encoder_hidden_states,
                                encoder_attention_mask=encoder_attention_mask,
                                disable_a2v_cross_attn=True,
                                disable_v2a_cross_attn=True,
                            )
                        )

                    execution_pass_specs = (
                        [
                            pass_spec
                            for index, pass_spec in enumerate(pass_specs)
                            if index % stage1_cfg_world_size == stage1_cfg_rank
                        ]
                        if stage1_cfg_parallel
                        else pass_specs
                    )
                    num_execution_passes = len(execution_pass_specs)
                    if num_execution_passes == 0:
                        raise ValueError(
                            "LTX2 stage-1 CFG parallel degree exceeds guidance pass count."
                        )
                    expanded_batch_size = batch_size_local * num_execution_passes
                    batched_model_kwargs = self._repeat_ltx2_model_kwargs_batch(
                        base_model_kwargs_local, expanded_batch_size
                    )
                    batched_model_kwargs = self._build_ltx2_model_kwargs(
                        ctx,
                        batched_model_kwargs,
                        encoder_hidden_states=torch.cat(
                            [
                                pass_spec.encoder_hidden_states
                                for pass_spec in execution_pass_specs
                            ],
                            dim=0,
                        ),
                        audio_encoder_hidden_states=torch.cat(
                            [

View on GitHub (pinned to 0132848349)

Solutions

1. Lower the stage-1 CFG parallel degree so it is <= the guidance pass count (typically 2 for CFG)
2. Add guidance passes (e.g. enable distorted/cFG variants) if you need a higher degree
3. Disable stage1_cfg_parallel for this sampling mode

Example fix

# before
--stage1-cfg-parallel 4   # only 2 guidance passes -> raises
# after
--stage1-cfg-parallel 2

if stage1_cfg_parallel:
    assert cfg_parallel_degree <= len(pass_specs), "CFG parallel degree exceeds guidance passes"

When it happens

Trigger: stage1_cfg_parallel enabled with a parallel degree larger than len(pass_specs) — e.g. degree 4 with only 2 passes (cond + uncond).

Common situations: Raising --cfg-parallel / DP degree without adding guidance passes; a multi-GPU launch where world size divides into CFG passes and the local degree is miscomputed; enabling CFG parallel on an unconditional-free sampling mode.

Related errors

• world_size must be positive and divide global_heads
• padding_side must be 'left' or 'right', got {padding_side}
• Unsupported text encoder output: expected `hidden_states`.
• num_inference_steps must be positive, got {steps}
• LTX-2 SP time-sharding for packed token latents currently re

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