sgl-project/sglang · error · ValueError

Latents must be provided

Error message

Latents must be provided

What it means

The Hunyuan3D denoising loop requires initial latents on the batch, normally produced by the _prepare_latents step or an equivalent upstream stage. batch.latents is None means no initial noise tensor was generated or passed in, so denoising cannot start.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/hunyuan3d/shape.py:328

        assert scheduler is not None
        cache_dit_num_inference_steps = batch.extra.get(
            "cache_dit_num_inference_steps", batch.num_inference_steps
        )
        freshly_loaded = load_transformer_if_needed(self, server_args)
        if freshly_loaded:
            self._maybe_enable_cache_dit(cache_dit_num_inference_steps, batch)
            self._maybe_torch_compile(self.transformer)
            register_loaded_transformer(self, server_args, pipeline)
        else:
            self._maybe_enable_cache_dit(cache_dit_num_inference_steps, batch)

        timesteps = batch.timesteps
        if timesteps is None:
            raise ValueError("Timesteps must be provided")

        latents = batch.latents
        if latents is None:
            raise ValueError("Latents must be provided")

        cond = batch.prompt_embeds[0] if batch.prompt_embeds else None
        if cond is None:
            raise ValueError("Conditioning (prompt_embeds) must be provided")

        if batch.raw_latent_shape is None:
            batch.raw_latent_shape = latents.shape

        guidance = batch.extra.get("shape_guidance")
        num_inference_steps = batch.num_inference_steps
        num_warmup_steps = len(timesteps) - num_inference_steps * scheduler.order

        extra_step_kwargs = self.prepare_extra_func_kwargs(
            scheduler.step,
            {"generator": batch.generator, "eta": batch.eta},
        )

        target_dtype = next(self.transformer.parameters()).dtype

View on GitHub (pinned to 0132848349)

Solutions

1. Run the latent-preparation stage (or _prepare_latents) before the denoising loop so batch.latents is populated
2. If building batches manually, generate latents with the expected shape (batch_size, *latent_shape) and assign to batch.latents
3. Verify pipeline stage ordering and that no stage was conditionally skipped

Example fix

# before
batch.latents = None

# after
from diffusers.utils.torch_utils import randn_tensor
batch.latents = randn_tensor((1, *stage.latent_shape), generator=gen,
                             device=dev, dtype=dt)

if batch.latents is None:
    from diffusers.utils.torch_utils import randn_tensor
    batch.latents = randn_tensor((1, *stage.latent_shape),
                                 generator=gen, device=dev, dtype=dt)

def has_latents(batch) -> bool:
    return getattr(batch, "latents", None) is not None

When it happens

Trigger: Invoking the denoising-loop stage directly without a preceding latent-preparation stage; manual batch construction omitting latents; latent-prep stage skipped because of a condition (e.g. disabled random init) or a failed generator.

Common situations: Reordered/partial pipelines in tests; refactor decoupling latent prep from the loop; providing latents under a different attribute name (e.g. latents_1 instead of latents).

Related errors

• Timesteps must be provided
• Conditioning (prompt_embeds) must be provided
• SANA-WM denoising requires initialized latents.
• The native SD2 UNet currently supports only the Hunyuan3D fo
• Hunyuan3D SD2.1 UNet requires four channel stages.

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