{"record":{"id":"b0b791c4e26099d7","repo":"sgl-project/sglang","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":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d.py","lineNumber":589,"sourceCode":"        contexts,\n        **kwargs,\n    ) -> torch.Tensor:\n        \"\"\"Forward pass for denoising.\"\"\"\n\n        cond = contexts[\"main\"]\n\n        latent = self.latent_in(x)\n\n        t_emb = _flux_timestep_embedding(t, 256, self.time_factor).to(\n            dtype=latent.dtype\n        )\n\n        vec = self.time_in(t_emb)\n\n        if self.guidance_embed:\n            guidance = kwargs.get(\"guidance\", None)\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(\n                _flux_timestep_embedding(guidance, 256, self.time_factor)\n            )\n\n        cond = self.cond_in(cond)\n\n        pe = None\n\n        # Double blocks\n        for i, block in enumerate(self.double_blocks):\n            latent, cond = block(img=latent, txt=cond, vec=vec, pe=pe)\n        latent = torch.cat((cond, latent), 1)\n\n        # Single blocks\n        for i, block in enumerate(self.single_blocks):\n            latent = block(latent, vec=vec, pe=pe)","sourceCodeStart":571,"sourceCodeEnd":607,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/hunyuan3d.py#L571-L607","documentation":"The Hunyuan3D transformer was built with guidance_embed=True (guidance-distilled), so every forward pass needs a guidance value to embed and add to the timestep vector. forward raises this ValueError when kwargs contains no 'guidance' key (or it is None).","triggerScenarios":"Calling model forward on a guidance-distilled Hunyuan3D checkpoint without kwargs['guidance'], e.g. running a CFG-style sampling loop that assumes no guidance embedding is needed.","commonSituations":"Using a distillation-capable checkpoint with a sampler written for the non-distilled model; guidance key dropped when building a kwargs dict dynamically.","solutions":["Pass guidance=... in the model kwargs each step (typical distilled value ~3.5 for Hunyuan3D)","If you want classifier-free guidance instead, load/use a non-distilled config where guidance_embed=False","Double-check your pipeline builds kwargs with the 'guidance' key for distilled checkpoints"],"exampleFix":"# before\nout = model(hidden_states, timestep=t, context=ctx)\n\n# after\nout = model(hidden_states, timestep=t, context=ctx, guidance=torch.tensor([3.5]))","handlingStrategy":"validation","validationCode":"if model.guidance_embed:\n    assert kwargs.get('guidance') is not None, 'distilled model requires kwargs[\"guidance\"]'","typeGuard":"def needs_guidance(model) -> bool:\n    return getattr(model, 'guidance_embed', False)","tryCatchPattern":"try:\n    out = model(h, t, **kwargs)\nexcept ValueError as e:\n    if 'guidance strength' in str(e) and model.guidance_embed:\n        kwargs['guidance'] = torch.tensor([3.5], device=h.device)\n        out = model(h, t, **kwargs)\n    else:\n        raise","preventionTips":["Branch sampler setup on guidance_embed from the config","Default guidance to ~3.5 for distilled Hunyuan checkpoints","Log which kwargs each denoise step receives during pipeline bring-up"],"tags":["runtime","diffusion","guidance-distillation","missing-argument"],"backgroundTag":"missing-guidance-embedding","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}