sgl-project/sglang · error · ValueError

Missing required argument for SparseVideoGen2Attention: {nam

Error message

Missing required argument for SparseVideoGen2Attention: {name}

What it means

The SparseVideoGen2 attention metadata builder uses _require_kwarg to pull mandatory arguments out of the kwargs dict. If a required key (e.g. raw_latent_shape, patch_size, cu_seqlens, etc.) is absent, it raises ValueError naming the missing argument.

Source

Thrown at python/sglang/multimodal_gen/runtime/layers/attention/backends/sparse_video_gen_2_attn.py:112

    top_p_kmeans: float
    min_kc_ratio: float
    kmeans_iter_init: int
    kmeans_iter_step: int
    zero_step_kmeans_init: bool
    first_layers_fp: float
    first_times_fp: float
    context_length: int
    num_frame: int
    frame_size: int
    cache: Svg2Cache
    prompt_length: int | None = None
    max_seqlen_q: int | None = None
    max_seqlen_k: int | None = None


def _require_kwarg(kwargs: dict[str, Any], name: str) -> Any:
    if name not in kwargs:
        raise ValueError(
            f"Missing required argument for SparseVideoGen2Attention: {name}"
        )
    return kwargs[name]


class SparseVideoGen2AttentionMetadataBuilder(AttentionMetadataBuilder):

    def __init__(self) -> None:
        pass

    def prepare(self) -> None:
        pass

    def build(  # type: ignore[override]
        self,
        current_timestep: int,
        raw_latent_shape: tuple[int, ...],
        patch_size: tuple[int, int, int],

View on GitHub (pinned to 0132848349)

Solutions

1. Inspect _require_kwarg call sites in the file to get the exact required key list, and pass every one in the kwargs dict.
2. Fix naming mismatches between what your model passes and what the builder expects (e.g. raw_latent_shape, not latent_shape).
3. Update the calling model code to always include the video latent geometry metadata when this backend is selected.

Example fix

# before
meta = builder.build(kwargs={"cu_seqlens": cu})  # ValueError: Missing required argument ... raw_latent_shape

# after
meta = builder.build(kwargs={
    "cu_seqlens": cu,
    "raw_latent_shape": (T, H, W),
    "patch_size": (pt, ph, pw),
})

REQUIRED = {"raw_latent_shape", "patch_size"}  # from _require_kwarg call sites
missing = REQUIRED - kwargs.keys()
assert not missing, f"missing kwargs: {missing}"
meta = builder.build(kwargs=kwargs)

def has_required_kwargs(kwargs: dict, required: set[str]) -> bool:
    return required.issubset(kwargs.keys())

try:
    meta = builder.build(kwargs=kwargs)
except ValueError as e:
    if "Missing required argument" in str(e):
        raise TypeError(f"bad metadata for SVG2: {e}") from e
    raise

When it happens

Trigger: Calling the builder's build/metadata path with a kwargs dict that omits one of the required keys consumed via _require_kwarg — e.g. forgetting raw_latent_shape or patch_size when constructing attention metadata for a Sparse Video Gen 2 (SVG2) DiT layer.

Common situations: Integrating SVG2 attention into a new model pipeline where the model's forward doesn't forward all metadata keys; partial refactors that rename kwargs (raw_shape vs raw_latent_shape); or a model variant that doesn't compute patch grids.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid attention metadata values.Sparsity should be in [0,
• Invalid attention metadata values.Sparsity should be in [0,
• component_attention_backends must use component=backend entr
• Component attention backend key must not be empty
• v_cache must be provided

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