hpcaitech/Open-Sora · error · ValueError

Didn't get guidance strength for guidance distilled model.

Error message

Didn't get guidance strength for guidance distilled model.

What it means

When config.guidance_embed=True the MMDiT is a guidance-distilled model: its time embedding vector also consumes an embedded guidance scale (vec += guidance_in(timestep_embedding(guidance, 256))). Calling forward with guidance=None in that mode raises.

Source

Thrown at opensora/models/mmdit/model.py:185

            img: projected noisy img latent,
            txt: text context (from t5),
            vec: clip encoded vector,
            pe: the positional embeddings for concatenated img and txt
        """
        if img.ndim != 3 or txt.ndim != 3:
            raise ValueError("Input img and txt tensors must have 3 dimensions.")

        # running on sequences img
        img = self.img_in(img)
        if self.config.cond_embed:
            if cond is None:
                raise ValueError("Didn't get conditional input for conditional model.")
            img = img + self.cond_in(cond)

        vec = self.time_in(timestep_embedding(timesteps, 256))
        if self.config.guidance_embed:
            if guidance is None:
                raise ValueError(
                    "Didn't get guidance strength for guidance distilled model."
                )
            vec = vec + self.guidance_in(timestep_embedding(guidance, 256))
        vec = vec + self.vector_in(y_vec)

        txt = self.txt_in(txt)

        # concat: 4096 + t*h*2/4
        ids = torch.cat((txt_ids, img_ids), dim=1)
        pe = self.pe_embedder(ids)

        if self._input_requires_grad:
            # we only apply lora to double/single blocks, thus we only need to enable grad for these inputs
            img.requires_grad_()
            txt.requires_grad_()

        return img, txt, vec, pe

View on GitHub (pinned to 7ad6a96a13)

Solutions

1. Pass guidance=... (e.g. a scalar/batched value like 3.5) to forward
2. If running a non-distilled checkpoint, set config.guidance_embed=False so the branch is skipped
3. Set up a sampler/inference helper that always supplies guidance for distilled models

Example fix

# before
out = model(img, txt, timesteps, y_vec=y_vec)  # guidance_embed=True
# after
out = model(img, txt, timesteps, y_vec=y_vec, guidance=torch.tensor(3.5, device=img.device))

if model.config.guidance_embed:
    assert guidance is not None, "guidance-distilled model requires a guidance value"

def needs_guidance(model) -> bool:
    return bool(getattr(model.config, "guidance_embed", False))

try:
    out = model(img, txt, t, y_vec=y_vec, guidance=guidance)
except ValueError as e:
    if "guidance strength" in str(e):
        raise TypeError("guidance-distilled checkpoint; pass guidance= (e.g. 3.5)") from e
    raise

When it happens

Trigger: Forwarding the model with config.guidance_embed=True without passing the guidance value (the distillation guidance scale), on any of the forward paths (mmdit_model_forward, forward_ckpt, forward_selective_ckpt).

Common situations: Reusing an inference script written for non-distilled MMDiT (Flux-style) checkpoints with a guidance-distilled one; forgetting the guidance kwarg when guidance_distilled=True in the config.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Didn't get conditional input for conditional model.
• Hidden size {config.hidden_size} must be divisible by num_he
• Got {config.axes_dim} but expected positional dim {pe_dim}
• Input img and txt tensors must have 3 dimensions.
• ContextParallelAttention should not be initialized directly.

AI-assisted analysis of hpcaitech/Open-Sora@7ad6a96a13 (2026-08-28). Data as JSON: /api/errors/2ca728d78f2246b6. Report an issue: GitHub.