sgl-project/sglang · critical · ValueError

SP-sharded LTX-2 TI2V expected raw seq_len divisible by toke

Error message

SP-sharded LTX-2 TI2V expected raw seq_len divisible by tokens_per_frame.

What it means

During sequence-parallel (SP) sharded LTX-2 text/image-to-video generation, the stage computes per-rank frame spans by dividing the global raw latent sequence length by tokens_per_frame. If batch.raw_latent_shape[1] is not an integer multiple of tokens_per_frame, the frame arithmetic breaks and this ValueError is thrown.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/ltx_2/denoising.py:998

                (int(latents.shape[1]) - int(num_img_tokens), condition_latents[1]),
            ]

        tokens_per_frame = int(getattr(batch, "sp_video_tokens_per_frame", 0))
        if tokens_per_frame <= 0:
            raise ValueError(
                "SP-sharded LTX-2 TI2V requires batch.sp_video_tokens_per_frame."
            )
        if int(num_img_tokens) != int(tokens_per_frame):
            raise ValueError(
                "LTX-2 conditioning token count must match one latent frame when using SP."
            )

        raw_shape = getattr(batch, "raw_latent_shape", None)
        if raw_shape is None:
            raise ValueError("SP-sharded LTX-2 TI2V requires batch.raw_latent_shape.")
        global_seq_len = int(raw_shape[1])
        if global_seq_len % tokens_per_frame != 0:
            raise ValueError(
                "SP-sharded LTX-2 TI2V expected raw seq_len divisible by tokens_per_frame."
            )

        global_num_frames = global_seq_len // tokens_per_frame
        local_start_frame = int(getattr(batch, "sp_video_start_frame", 0))
        local_num_frames = int(getattr(batch, "sp_video_latent_num_frames", 0))
        local_end_frame = local_start_frame + local_num_frames

        spans: list[tuple[int, torch.Tensor]] = []
        if local_start_frame == 0:
            spans.append((0, condition_latents[0]))

        if len(condition_latents) == 2:
            last_global_frame = global_num_frames - 1
            if local_start_frame <= last_global_frame < local_end_frame:
                local_last_frame = last_global_frame - local_start_frame
                spans.append(
                    (local_last_frame * tokens_per_frame, condition_latents[1])

View on GitHub (pinned to 0132848349)

Solutions

1. Verify batch.raw_latent_shape[1] equals num_frames * tokens_per_frame before launching the SP run
2. Adjust frame count / resolution so the latent seq_len is frame-aligned
3. Check that tokens_per_frame matches the LTX-2 latent patching config for this checkpoint

Example fix

// before
batch.raw_latent_shape = (1, 12345, 64)  // 12345 % tokens_per_frame != 0
// after
assert global_seq_len % tokens_per_frame == 0
batch.raw_latent_shape = (1, num_frames * tokens_per_frame, 64)

tokens_per_frame = get_tokens_per_frame(ckpt)
seq_len = int(batch.raw_latent_shape[1])
assert seq_len % tokens_per_frame == 0, f"seq_len {seq_len} not frame-aligned (tokens_per_frame={tokens_per_frame})"

When it happens

Trigger: Running an SP-sharded LTX-2 TI2V pipeline where batch.raw_latent_shape[1] (global_seq_len) % tokens_per_frame != 0, e.g. a latent shape that doesn't correspond to whole frames, or a wrong tokens_per_frame for the checkpoint.

Common situations: Mismatched resolution/duration settings producing non-frame-aligned latent lengths; using an SP degree or VA chunking that yields a partial final frame; feeding a raw_latent_shape computed from pixels instead of latents.

Related errors

• Invalid {self.vae_scale_factor=}. Must be > 0.
• Invalid {self.patch_size=}. Must be > 0.
• Invalid latent H/W computed from batch.height/width: {batch.
• Invalid spatial patching for packed token latents. Expected
• Invalid tokens_per_frame={tokens_per_frame} from {latent_hei

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