sgl-project/sglang · error · RuntimeError

deepstack_visual_indexes exists but deepstack_merger_list is

Error message

deepstack_visual_indexes exists but deepstack_merger_list is missing.

What it means

For models with deepstack (Qwen3-VL style), the runner was given per-layer deepstack_visual_indexes but no corresponding deepstack_merger_list modules, so it cannot compute deepstack outputs during graph capture. This indicates inconsistent construction arguments.

Source

Thrown at python/sglang/srt/multimodal/vit_cuda_graph_runner.py:244

                            rotary_pos_emb_sin=rotary_pos_emb_sin,
                            output_ws=self.block_ws[graph_key],
                        )
                    else:
                        y = blk(
                            y,
                            cu_seqlens=cu_seq_len_ws,
                            rotary_pos_emb_cos=rotary_pos_emb_cos,
                            rotary_pos_emb_sin=rotary_pos_emb_sin,
                            output_ws=self.block_ws[graph_key],
                        )

                # Optional deepstack support (Qwen3-VL)
                if (
                    self._deepstack_visual_indexes
                    and layer_num in self._deepstack_visual_indexes
                ):
                    if self._deepstack_merger_list is None:
                        raise RuntimeError(
                            "deepstack_visual_indexes exists but deepstack_merger_list is missing."
                        )
                    deepstack_out = self._deepstack_merger_list[deepstack_capture_idx](
                        y
                    )
                    deepstack_outs.append(deepstack_out)
                    deepstack_capture_idx += 1

            main_out = vit.merger(y)

            if deepstack_outs:
                self.block_output[graph_key] = torch.cat(
                    [main_out] + deepstack_outs, dim=1
                )
            else:
                self.block_output[graph_key] = main_out

        self.block_graphs[graph_key] = graph

View on GitHub (pinned to 0132848349)

Solutions

1. Pass the full merger module list (deepstack_merger_list=[...]) matching the deepstack layers
2. If deepstack is not intended, clear deepstack_visual_indexes so the branch is skipped
3. Verify the model adapter wires both parameters from the same config source

Example fix

# before
runner = VitCudaGraphRunner(..., deepstack_visual_indexes=idx, deepstack_merger_list=None)
# after
runner = VitCudaGraphRunner(..., deepstack_visual_indexes=idx, deepstack_merger_list=mergers)

if deepstack_visual_indexes:
    assert deepstack_merger_list is not None, 'deepstack_merger_list required'

def deepstack_args_consistent(indexes, mergers) -> bool:
    return not indexes or mergers is not None

When it happens

Trigger: Instantiating the ViT cuda-graph runner with deepstack_visual_indexes non-empty while passing deepstack_merger_list=None (or forgetting to pass it).

Common situations: Adding deepstack support piecemeal; a model adapter supplying visual indexes but its merger modules failing to load; refactors that renamed the merger-list kwarg so it silently defaults to None.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• ViT CUDA graph does not support attention backend: {backend}
• Z-Image caption tensor must have rank 2 or 3
• output_ws should be prepared for cuda-graph mode
• {config.text_config.architectures[0]} is not implemented.
• cos/sin shape does not cover image tokens and head_dim

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