sgl-project/sglang · error · ValueError

Expected packed image latents [B, S0, D].

Error message

Expected packed image latents [B, S0, D].

What it means

The LTX-2 image encoding stage packs per-image VAE latents via pipeline_config.maybe_pack_latents() and requires the result to be a 3-D torch.Tensor of shape [B, S0, D] (batch, packed token slots, latent dim). If maybe_pack_latents returns a non-tensor (e.g. None because packing is not enabled or not applicable) or a tensor of the wrong rank, the stage refuses to continue because downstream transformer conditioning expects exactly this layout.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/image_encoding.py:794

                    device=device,
                    dtype=encode_dtype,
                )

                # 3. Encode
                if use_condition_encoder:
                    latent = self._condition_encode(video_condition, server_args).to(
                        dtype=encode_dtype
                    )
                else:
                    latent = self._vae_encode(
                        video_condition, server_args, batch.generator
                    )

                packed = server_args.pipeline_config.maybe_pack_latents(
                    latent, latent.shape[0], batch
                )
                if not (isinstance(packed, torch.Tensor) and packed.ndim == 3):
                    raise ValueError("Expected packed image latents [B, S0, D].")
                if int(packed.shape[1]) != expected_tokens:
                    raise ValueError(
                        f"LTX-2 conditioning token count mismatch: "
                        f"{packed.shape[1]=} {expected_tokens=}."
                    )
                packed_latents.append(packed)

        batch.image_latent = (
            packed_latents[0] if len(packed_latents) == 1 else packed_latents
        )
        batch.ltx2_num_image_tokens = int(packed_latents[0].shape[1])

        if batch.debug:
            logger.info(
                "LTX2 TI2V: %d tokens (shape=%s) for %sx%s",
                batch.ltx2_num_image_tokens,
                tuple(packed_latents[0].shape),
                batch.width,

View on GitHub (pinned to 0132848349)

Solutions

1. Check what pipeline_config.maybe_pack_latents returns for your config — if packing is disabled it returns the latent unchanged, so enable the LTX-2 packing option in pipeline_config
2. Inspect latent.shape before the call: a rank-4 [B,C,H,W] VAE latent must be reshaped/packed to [B, S0, D] first
3. Verify server_args.pipeline_config actually corresponds to the LTX-2 task/pipeline you are running (not a generic image pipeline)
4. Update to a matching sglang version where maybe_pack_latents and the image_encoding stage agree on the packed-latent contract

Example fix

// before
packed = server_args.pipeline_config.maybe_pack_latents(latent, latent.shape[0], batch)

// after (ensure VAE latent is flattened to tokens before packing)
if latent.ndim == 4:
    latent = latent.reshape(latent.shape[0], -1, latent.shape[-1])
packed = server_args.pipeline_config.maybe_pack_latents(latent, latent.shape[0], batch)

packed = server_args.pipeline_config.maybe_pack_latents(latent, latent.shape[0], batch)
assert isinstance(packed, torch.Tensor) and packed.ndim == 3, f"bad packed latent: {type(packed)} {getattr(packed, 'shape', None)}"

def is_packed_latents(x) -> bool:
    return isinstance(x, torch.Tensor) and x.ndim == 3

When it happens

Trigger: Calling the multimodal generation pipeline with an LTX-2 image-encoding config where maybe_pack_latents() is a no-op returning the input latent unchanged (rank != 3), or where the VAE output for a reference/conditioning image has unexpected shape (e.g. a 4-D [B,C,H,W] latent or a tuple/distribution object) while the LTX-2 packing path is active.

Common situations: Mixing a non-LTX-2 VAE/config with the LTX-2 conditioning path; enabling or disabling latent packing flags inconsistently with the pipeline config; passing precomputed latents of different rank; version changes that alter maybe_pack_latents return contract.

Related errors

• kv-canary: {name} must be on {reference_name}'s device {refe
• kv-canary: scatter_req_token_ids flat_in must be int64, got
• kv-canary: scatter_req_token_ids offsets must be int64, got
• kv-canary: scatter_req_token_ids req_pool_indices must be in
• kv-canary: scatter_req_token_ids pool_out must be int32, got

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