{"record":{"id":"e5c62bb4dac2ea6f","repo":"sgl-project/sglang","slug":"ltx2-stage-1-cfg-parallel-degree-exceeds-guidance","errorCode":null,"errorMessage":"LTX2 stage-1 CFG parallel degree exceeds guidance pass count.","messagePattern":"LTX2 stage-1 CFG parallel degree exceeds guidance pass count\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/ltx_2/denoising.py","lineNumber":2204,"sourceCode":"                                audio_encoder_hidden_states=audio_encoder_hidden_states,\n                                encoder_attention_mask=encoder_attention_mask,\n                                disable_a2v_cross_attn=True,\n                                disable_v2a_cross_attn=True,\n                            )\n                        )\n\n                    execution_pass_specs = (\n                        [\n                            pass_spec\n                            for index, pass_spec in enumerate(pass_specs)\n                            if index % stage1_cfg_world_size == stage1_cfg_rank\n                        ]\n                        if stage1_cfg_parallel\n                        else pass_specs\n                    )\n                    num_execution_passes = len(execution_pass_specs)\n                    if num_execution_passes == 0:\n                        raise ValueError(\n                            \"LTX2 stage-1 CFG parallel degree exceeds guidance pass count.\"\n                        )\n                    expanded_batch_size = batch_size_local * num_execution_passes\n                    batched_model_kwargs = self._repeat_ltx2_model_kwargs_batch(\n                        base_model_kwargs_local, expanded_batch_size\n                    )\n                    batched_model_kwargs = self._build_ltx2_model_kwargs(\n                        ctx,\n                        batched_model_kwargs,\n                        encoder_hidden_states=torch.cat(\n                            [\n                                pass_spec.encoder_hidden_states\n                                for pass_spec in execution_pass_specs\n                            ],\n                            dim=0,\n                        ),\n                        audio_encoder_hidden_states=torch.cat(\n                            [","sourceCodeStart":2186,"sourceCodeEnd":2222,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/ltx_2/denoising.py#L2186-L2222","documentation":"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.","triggerScenarios":"stage1_cfg_parallel enabled with a parallel degree larger than len(pass_specs) — e.g. degree 4 with only 2 passes (cond + uncond).","commonSituations":"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.","solutions":["Lower the stage-1 CFG parallel degree so it is <= the guidance pass count (typically 2 for CFG)","Add guidance passes (e.g. enable distorted/cFG variants) if you need a higher degree","Disable stage1_cfg_parallel for this sampling mode"],"exampleFix":"# before\n--stage1-cfg-parallel 4   # only 2 guidance passes -> raises\n# after\n--stage1-cfg-parallel 2","handlingStrategy":"validation","validationCode":"if stage1_cfg_parallel:\n    assert cfg_parallel_degree <= len(pass_specs), \"CFG parallel degree exceeds guidance passes\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate degree vs pass count at server startup, not mid-step","Default CFG parallel to 2 for cond/uncond"],"tags":["ltx-2","cfg-parallel","config-mismatch","distributed"],"backgroundTag":"parallelism-degree-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}