sgl-project/sglang · error · ValueError

Height and width must be provided

Error message

Height and width must be provided

What it means

LatentPreparationStage needs the spatial dimensions (height and width) of the output latent for this model/pipeline configuration, but the batch carries None for one or both. Without them the stage cannot shape the initial noise latent, so it raises before generating latents.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/latent_preparation.py:135

        """

        # Adjust video length based on VAE version if needed
        latent_num_frames = self.get_forward_latent_num_frames(batch, server_args)

        batch_size = batch.batch_size

        # Get required parameters
        device = get_local_torch_device()
        generator = batch.generator
        latents = batch.latents
        height = batch.height
        width = batch.width

        # TODO(will): remove this once we add input/output validation for stages
        if self.requires_batch_height_width(batch, server_args) and (
            height is None or width is None
        ):
            raise ValueError("Height and width must be provided")

        # Validate generator if it's a list
        if isinstance(generator, list) and len(generator) != batch_size:
            raise ValueError(
                f"You have passed a list of generators of length {len(generator)}, but requested an effective batch"
                f" size of {batch_size}. Make sure the batch size matches the length of the generators."
            )

        # Generate or use provided latents
        if latents is None:
            spec = self.get_latent_preparation_spec(
                batch, server_args, batch_size, latent_num_frames, device
            )
            latents = randn_tensor(
                spec.shape,
                generator=generator,
                device=spec.device,
                dtype=spec.dtype,

View on GitHub (pinned to 0132848349)

Solutions

1. Pass explicit height and width in the request (e.g. height=1024, width=1024)
2. If the model has a canonical resolution, set it as the default in server_args/model config so the batch always carries values
3. Check that any upstream stage responsible for resolving resolution ran before LatentPreparationStage
4. If you maintain the stage, wire the height/width defaults into requires_batch_height_width's callers instead of relying on the request

Example fix

# before
out = pipe(prompt="a cat")
# after
out = pipe(prompt="a cat", height=1024, width=1024)

if batch.height is None or batch.width is None:
    raise ValueError("height/width required before running the pipeline")

def has_resolution(batch) -> bool:
    return isinstance(batch.height, int) and isinstance(batch.width, int) and batch.height > 0 and batch.width > 0

When it happens

Trigger: Calling the pipeline/stage without height/width when requires_batch_height_width(batch, server_args) returns True — typical for models whose latent shape is not inferred from inputs (no explicit resolution and no default), e.g. an LLM-only or DiT model without a config-provided resolution.

Common situations: Porting a diffusers script that always passed height/width explicitly; a new model integration that forgot to set per-request defaults in server_args or model config; multipart pipelines where a prior stage was expected to populate batch.width/height but was skipped or reordered.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• 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()}
• The batch size is expected to be 1 rather than {q.shape[0]}

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