{"record":{"id":"b9876550755107ec","repo":"sgl-project/sglang","slug":"mova-requires-reference-image-latents-for-denoisin","errorCode":null,"errorMessage":"MOVA requires reference image latents for denoising","messagePattern":"MOVA requires reference image latents for denoising","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/mova.py","lineNumber":124,"sourceCode":"        generator = batch.generator\n        if isinstance(generator, list) and len(generator) != batch_size:\n            raise ValueError(\n                f\"You have passed a list of generators of length {len(generator)}, but requested an effective batch\"\n                f\" size of {batch_size}. Make sure the batch size matches the length of the generators.\"\n            )\n\n        dit_dtype = PRECISION_TO_TYPE[server_args.pipeline_config.dit_precision]\n        batch.latents = randn_tensor(\n            video_shape, generator=generator, device=device, dtype=dit_dtype\n        )\n        batch.audio_latents = randn_tensor(\n            audio_shape, generator=generator, device=device, dtype=dit_dtype\n        )\n\n        if batch.image_latent is not None:\n            batch.y = batch.image_latent.to(device=device, dtype=dit_dtype)\n        elif self.require_vae_embedding:\n            raise ValueError(\"MOVA requires reference image latents for denoising\")\n        return batch\n\n\nclass MOVATimestepPreparationStage(PipelineStage):\n    \"\"\"Prepare paired timesteps for MOVA.\"\"\"\n\n    def __init__(self, scheduler) -> None:\n        super().__init__()\n        self.scheduler = scheduler\n\n    def forward(self, batch: Req, server_args: ServerArgs) -> Req:\n        scheduler = self.scheduler\n        scheduler.set_timesteps(\n            batch.num_inference_steps,\n            denoising_strength=1.0,\n            shift=getattr(batch, \"sigma_shift\", scheduler.shift),\n        )\n        scheduler.set_pair_postprocess_by_name(","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/mova.py#L106-L142","documentation":"The MOVA latent-preparation stage needs a reference image latent (batch.y) to condition denoising when the video DiT is configured with require_vae_embedding. If batch.image_latent is None and the model requires VAE embeddings, no conditioning signal exists and the stage refuses to proceed.","triggerScenarios":"Running the MOVA pipeline with a video DiT whose require_vae_embedding attribute is truthy while the incoming batch carries image_latent=None (no reference image was VAE-encoded upstream).","commonSituations":"Image-to-video request submitted without a reference image, an upstream VAE-encode stage skipped or failed silently, or image conditioning accidentally disabled in the pipeline config.","solutions":["Provide a reference image for the request so the upstream stage populates batch.image_latent","Check the upstream VAE encoding stage ran and its output was attached to batch.image_latent","If unconditional generation is intended, use a model/config where require_vae_embedding is False"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if getattr(model, 'require_vae_embedding', False):\n    if batch.image_latent is None:\n        raise ValueError('reference image required for this MOVA config — attach one before forward')","typeGuard":"def has_reference_latent(batch) -> bool:\n    return batch.y is not None or batch.image_latent is not None","tryCatchPattern":"try:\n    stage.forward(batch)\nexcept ValueError as e:\n    if 'reference image latents' in str(e):\n        return error_response('image-to-video requires a reference image')\n    raise","preventionTips":["Validate reference image presence at request admission for i2v models","Log when the VAE encode stage produces None so failures surface early","Keep pipeline config's require_vae_embedding in sync with the loaded checkpoint"],"tags":["mova","image-latent","conditioning","validation"],"backgroundTag":"missing-required-conditional-input","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}