sgl-project/sglang · error · ValueError

num_frames must be positive

Error message

num_frames must be positive

What it means

SANA video pipeline's frame-count adjuster only accepts num_frames >= 1; zero or negative frame counts raise immediately. Valid counts are then snapped to the VAE temporal grid via ((n-1)//temporal_scale)*temporal_scale + 1.

Source

Thrown at python/sglang/multimodal_gen/configs/pipeline_configs/sana_video.py:69

                "add_special_tokens": True,
            }
        ]
    )
    preprocess_text_funcs: tuple[Callable[[str], str] | None, ...] = field(
        default_factory=lambda: (None,)
    )
    postprocess_text_funcs: tuple[Callable, ...] = field(
        default_factory=lambda: (sana_video_postprocess_text,)
    )

    def __post_init__(self) -> None:
        self.vae_config.load_encoder = False
        self.vae_config.load_decoder = True

    def adjust_num_frames(self, num_frames: int) -> int:
        temporal_scale = self.vae_config.arch_config.temporal_compression_ratio
        if num_frames < 1:
            raise ValueError("num_frames must be positive")
        return ((num_frames - 1) // temporal_scale) * temporal_scale + 1

    def prepare_latent_shape(self, batch, batch_size, num_frames):
        spatial_scale = self.vae_config.arch_config.spatial_compression_ratio
        return (
            batch_size,
            self.dit_config.arch_config.num_channels_latents,
            num_frames,
            batch.height // spatial_scale,
            batch.width // spatial_scale,
        )

    def get_latent_dtype(self, prompt_dtype: torch.dtype) -> torch.dtype:
        return torch.float32

    def get_pos_prompt_embeds(self, batch):
        return batch.prompt_embeds[0]

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a positive frame count (at least temporal_scale+1 for a valid multi-frame video)
2. Fix upstream computation: frame_count = max(1, int(duration * fps))
3. Set argparse default to a valid value like 33 and use type=int with a check

Example fix

# before
num_frames = int(duration * fps)  # duration=0 -> 0
num_frames = pipe.adjust_num_frames(num_frames)  # error

# after
num_frames = max(1, int(duration * fps))
num_frames = pipe.adjust_num_frames(num_frames)

if num_frames is None or num_frames < 1:
    raise ValueError("num_frames must be >= 1")
num_frames = pipe.adjust_num_frames(num_frames)

def is_positive_int(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 1

When it happens

Trigger: Calling adjust_num_frames with num_frames=0 or negative — often from an int(input)/argparse default of 0, a computed frame count that underflowed (e.g. num_frames - temporal_scale below 1), or dividing/mis-parsing a duration parameter.

Common situations: CLI default frames=0 left unset; frame count derived from duration*fps where duration=0; downstream loop that repeatedly subtracts the temporal scale until below 1.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• attn_sink requires topk_length to be provided as well
• missing value for {a} (expected e.g. `{a} 2,4`)
• combined_history=True requires direction=0 (bidi)
• attn_res: nvb must be in [1, {_MAX_BANK_ROWS}], got {nvb}
• kv-canary: launch_canary_plan_kernels requires full_to_swa_i

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