sgl-project/sglang · error · ValueError

Z-Image batch must contain at least one image latent

Error message

Z-Image batch must contain at least one image latent

What it means

Raised by ZImage.patchify_and_embed when all_image is empty. The forward path requires at least one image latent to embed; an empty batch has no valid work and downstream stacking would produce degenerate tensors.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/zimage.py:975

        patch_size: int,
        f_patch_size: int,
        image_seq_len_target: int | None = None,
        caption_valid_lens: torch.Tensor | None = None,
        caption_valid_mask: torch.Tensor | None = None,
    ):
        """Patchify images and pad image/caption tokens to batch targets.

        Each image is [C, F, H, W] and has one [L, D] caption. Returned tensors
        are stacked as [B, S, D], while valid lengths keep track of real tokens
        before learned pad tokens are restored. `image_seq_len_target`, when
        set, is the SP-local padded image-token target.
        """
        if len(all_image) != len(all_cap_feats):
            raise ValueError(
                f"Z-Image expects one caption embedding per image, got {len(all_image)} images and {len(all_cap_feats)} captions"
            )
        if not all_image:
            raise ValueError("Z-Image batch must contain at least one image latent")
        if caption_valid_mask is not None and caption_valid_mask.shape[0] != len(
            all_cap_feats
        ):
            raise ValueError("caption_valid_mask must have one row per Z-Image caption")

        pH = pW = patch_size
        pF = f_patch_size
        all_image_out = []
        all_image_size = []
        all_cap_feats_out = []
        all_image_valid_lens = []
        all_cap_valid_lens = []
        all_cap_valid_masks = []
        all_image_attn_lens = []
        all_cap_attn_lens = []
        image_records = []

        cap_seq_len_target = max(

View on GitHub (pinned to 0132848349)

Solutions

1. Skip the forward call when the batch is empty instead of invoking the model
2. Fix upstream filtering so at least one valid image/caption pair survives, or return early

Example fix

# before
if not batch: pass  # falls through to model
out = model(all_image=[], all_cap_feats=[])
# after
if not batch:
    return []
out = model(all_image=batch_images, all_cap_feats=batch_caps)

if not all_image:
    return []  # skip model call for empty batch

def is_nonempty_batch(images: list) -> bool:
    return len(images) > 0

When it happens

Trigger: Calling Z-Image forward with an empty list of image latents — e.g. all samples in the micro-batch were filtered out or the request batch was empty.

Common situations: A scheduler/filter step removed every sample (failed VAE encode, safety filter) leaving an empty batch that still reaches the model.

Related errors

• Z-Image text embeddings must have shape [seq, dim] or [batch
• v_cache must be provided
• q can only be None when only_qv=True
• q must be provided unless qv is provided with only_qv=True
• `dt_bias` must have {HV * K} elements (got {dt_bias.numel()}

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