{"record":{"id":"fc5bf880faf29e64","repo":"sgl-project/sglang","slug":"hunyuan3d-sd2-1-checkpoints-require-linear-project","errorCode":null,"errorMessage":"Hunyuan3D SD2.1 checkpoints require linear projection.","messagePattern":"Hunyuan3D SD2\\.1 checkpoints require linear projection\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py","lineNumber":100,"sourceCode":"            \"UpBlock2D\",\n            \"CrossAttnUpBlock2D\",\n            \"CrossAttnUpBlock2D\",\n            \"CrossAttnUpBlock2D\",\n        )\n        if self.down_block_types != expected_down or self.up_block_types != expected_up:\n            raise ValueError(\n                \"The native SD2 UNet currently supports only the Hunyuan3D \"\n                \"four-level SD2.1 block layout.\"\n            )\n        if len(self.block_out_channels) != 4 or len(self.attention_head_dim) != 4:\n            raise ValueError(\"Hunyuan3D SD2.1 UNet requires four channel stages.\")\n        if self.layers_per_block != 2 or self.transformer_layers_per_block != 1:\n            raise ValueError(\n                \"Hunyuan3D SD2.1 UNet requires two ResNet layers and one \"\n                \"transformer layer per block.\"\n            )\n        if not self.use_linear_projection:\n            raise ValueError(\"Hunyuan3D SD2.1 checkpoints require linear projection.\")\n\n\n@dataclass\nclass StableDiffusionUNetOutput:\n    sample: torch.Tensor\n\n\ndef timestep_embedding(\n    timesteps: torch.Tensor,\n    embedding_dim: int,\n    *,\n    flip_sin_to_cos: bool,\n    downscale_freq_shift: float,\n) -> torch.Tensor:\n    half_dim = embedding_dim // 2\n    exponent = -math.log(10000) * torch.arange(\n        half_dim, dtype=torch.float32, device=timesteps.device\n    )","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py#L82-L118","documentation":"Raised by StableDiffusionUNetConfig.validate() when use_linear_projection is falsy. Hunyuan3D SD2.1 checkpoints were exported with linear projection enabled in the attention blocks, and the native reimplementation assumes that layout.","triggerScenarios":"Loading an SD2 UNet config with use_linear_projection = false or omitting it while running the Hunyuan3D native UNet path.","commonSituations":"Using a vanilla SD2.1 base checkpoint (which does not use linear projection) with the Hunyuan3D-native loader; hand-written config dicts missing the flag.","solutions":["Set use_linear_projection = true in the UNet config","Use the Hunyuan3D SD2.1 checkpoint that was exported with linear projection"],"exampleFix":"// before\nuse_linear_projection = false\n// after\nuse_linear_projection = true","handlingStrategy":"validation","validationCode":"if not cfg_dict.get(\"use_linear_projection\", False):\n    cfg_dict[\"use_linear_projection\"] = True  # only if checkpoint actually uses it","typeGuard":"def uses_linear_projection(d: dict) -> bool:\n    return bool(d.get(\"use_linear_projection\"))","tryCatchPattern":null,"preventionTips":["Confirm the checkpoint was exported with linear projection before forcing the flag"],"tags":["stable-diffusion","unet","config-validation","hunyuan3d"],"backgroundTag":"config-validation-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}