{"record":{"id":"2ca728d78f2246b6","repo":"hpcaitech/Open-Sora","slug":"didn-t-get-guidance-strength-for-guidance-distille","errorCode":null,"errorMessage":"Didn't get guidance strength for guidance distilled model.","messagePattern":"Didn't get guidance strength for guidance distilled model\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"opensora/models/mmdit/model.py","lineNumber":185,"sourceCode":"            img: projected noisy img latent,\n            txt: text context (from t5),\n            vec: clip encoded vector,\n            pe: the positional embeddings for concatenated img and txt\n        \"\"\"\n        if img.ndim != 3 or txt.ndim != 3:\n            raise ValueError(\"Input img and txt tensors must have 3 dimensions.\")\n\n        # running on sequences img\n        img = self.img_in(img)\n        if self.config.cond_embed:\n            if cond is None:\n                raise ValueError(\"Didn't get conditional input for conditional model.\")\n            img = img + self.cond_in(cond)\n\n        vec = self.time_in(timestep_embedding(timesteps, 256))\n        if self.config.guidance_embed:\n            if guidance is None:\n                raise ValueError(\n                    \"Didn't get guidance strength for guidance distilled model.\"\n                )\n            vec = vec + self.guidance_in(timestep_embedding(guidance, 256))\n        vec = vec + self.vector_in(y_vec)\n\n        txt = self.txt_in(txt)\n\n        # concat: 4096 + t*h*2/4\n        ids = torch.cat((txt_ids, img_ids), dim=1)\n        pe = self.pe_embedder(ids)\n\n        if self._input_requires_grad:\n            # we only apply lora to double/single blocks, thus we only need to enable grad for these inputs\n            img.requires_grad_()\n            txt.requires_grad_()\n\n        return img, txt, vec, pe\n","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/hpcaitech/Open-Sora/blob/7ad6a96a135feb81f755c84fb391818718f6beb2/opensora/models/mmdit/model.py#L167-L203","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass guidance=... (e.g. a scalar/batched value like 3.5) to forward","If running a non-distilled checkpoint, set config.guidance_embed=False so the branch is skipped","Set up a sampler/inference helper that always supplies guidance for distilled models"],"exampleFix":"# before\nout = model(img, txt, timesteps, y_vec=y_vec)  # guidance_embed=True\n# after\nout = model(img, txt, timesteps, y_vec=y_vec, guidance=torch.tensor(3.5, device=img.device))","handlingStrategy":"validation","validationCode":"if model.config.guidance_embed:\n    assert guidance is not None, \"guidance-distilled model requires a guidance value\"","typeGuard":"def needs_guidance(model) -> bool:\n    return bool(getattr(model.config, \"guidance_embed\", False))","tryCatchPattern":"try:\n    out = model(img, txt, t, y_vec=y_vec, guidance=guidance)\nexcept ValueError as e:\n    if \"guidance strength\" in str(e):\n        raise TypeError(\"guidance-distilled checkpoint; pass guidance= (e.g. 3.5)\") from e\n    raise","preventionTips":["Default guidance to a scalar (e.g. 3.5) for distilled models","Check config.guidance_distilled/guidance_embed before running samplers","Keep distilled and non-distilled pipelines separate"],"tags":["transformer","mmdit","guidance","api-misuse"],"backgroundTag":"missing-required-argument","analyzedSha":"7ad6a96a135feb81f755c84fb391818718f6beb2","analyzedAt":"2026-08-28T16:58:37.171Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}