sgl-project/sglang · error · ValueError

LTX2 stage-1 CFG parallel degree exceeds guidance pass…

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.

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
Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

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


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

Appendix: 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)