sgl-project/sglang · error · ValueError

Invalid spatial patching for packed token latents. Expected

Error message

Invalid spatial patching for packed token latents. Expected latent H/W to be divisible by patch_size, got {latent_height=} {latent_width=} {self.patch_size=}.

What it means

LTX-2 SP time-sharding requires latent height and width to be divisible by patch_size so each frame patches into an integer grid of tokens. This check fires when batch.height/vae_scale_factor or batch.width/vae_scale_factor is not a multiple of patch_size, which would otherwise produce a fractional token grid.

Source

Thrown at python/sglang/multimodal_gen/configs/pipeline_configs/ltx_2.py:352

            )
        if int(seq_len) <= 0:
            raise ValueError(f"Expected {seq_len=} > 0 for packed token latents.")
        if int(self.vae_scale_factor) <= 0:
            raise ValueError(f"Invalid {self.vae_scale_factor=}. Must be > 0.")
        if int(self.patch_size) <= 0:
            raise ValueError(f"Invalid {self.patch_size=}. Must be > 0.")

        latent_height = int(batch.height) // int(self.vae_scale_factor)
        latent_width = int(batch.width) // int(self.vae_scale_factor)
        if latent_height <= 0 or latent_width <= 0:
            raise ValueError(
                "Invalid latent H/W computed from batch.height/width: "
                f"{batch.height=} {batch.width=} {self.vae_scale_factor=}"
            )
        if (latent_height % int(self.patch_size)) != 0 or (
            latent_width % int(self.patch_size)
        ) != 0:
            raise ValueError(
                "Invalid spatial patching for packed token latents. Expected latent H/W "
                "to be divisible by patch_size, got "
                f"{latent_height=} {latent_width=} {self.patch_size=}."
            )

        post_patch_h = latent_height // int(self.patch_size)
        post_patch_w = latent_width // int(self.patch_size)
        tokens_per_frame = int(post_patch_h) * int(post_patch_w)
        if tokens_per_frame <= 0:
            raise ValueError(
                f"Invalid tokens_per_frame={tokens_per_frame} from "
                f"{latent_height=} {latent_width=} {self.patch_size=}"
            )
        if int(seq_len) % int(tokens_per_frame) != 0:
            raise ValueError(
                f"LTX-2 token latents seq_len={seq_len} is not divisible by "
                f"tokens_per_frame={tokens_per_frame}. Cannot time-shard for SP."
            )

View on GitHub (pinned to 0132848349)

Solutions

1. Round the request resolution to the nearest multiple of vae_scale_factor * patch_size (e.g. multiples of 16 for factor 8 and patch 2)
2. Use the model's documented native resolutions (e.g. 768x1280, 1280x720-aligned values)
3. Confirm patch_size in the config matches the checkpoint's transformer patch size

Example fix

# before
batch = VideoBatch(height=500, width=860)
config.shard_latents_for_sp(batch)  # latent 62x107, not divisible by patch_size=2

# after
align = config.vae_scale_factor * config.patch_size
batch = VideoBatch(height=round(500/align)*align, width=round(860/align)*align)
config.shard_latents_for_sp(batch)

align = config.vae_scale_factor * config.patch_size
assert batch.height % align == 0 and batch.width % align == 0, (batch.height, batch.width, align)
batch = batch.evolve(height=round(batch.height/align)*align, width=round(batch.width/align)*align)

When it happens

Trigger: Calling shard_latents_for_sp with a resolution whose latent dims aren't multiples of patch_size, e.g. height=500, patch_size=2, vae_scale_factor=8 gives latent_height=62 which is not divisible by 2.

Common situations: Arbitrary user-supplied resolutions not rounded to the model's required grid; feeding resolution from a video file's native dimensions without quantizing; mismatched patch_size between config and checkpoint.

Related errors

• Invalid latent H/W computed from batch.height/width: {batch.
• Invalid {self.vae_scale_factor=}. Must be > 0.
• Invalid {self.patch_size=}. Must be > 0.
• Invalid tokens_per_frame={tokens_per_frame} from {latent_hei
• LTX-2 token latents seq_len={seq_len} is not divisible by to

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