{"record":{"id":"96642ef36a443072","repo":"sgl-project/sglang","slug":"hunyuan3d-sd2-1-unet-requires-two-resnet-layers-an","errorCode":null,"errorMessage":"Hunyuan3D SD2.1 UNet requires two ResNet layers and one transformer layer per block.","messagePattern":"Hunyuan3D SD2\\.1 UNet requires two ResNet layers and one transformer layer per block\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py","lineNumber":95,"sourceCode":"            \"CrossAttnDownBlock2D\",\n            \"CrossAttnDownBlock2D\",\n            \"DownBlock2D\",\n        )\n        expected_up = (\n            \"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,","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py#L77-L113","documentation":"Raised by StableDiffusionUNetConfig.validate() when layers_per_block != 2 or transformer_layers_per_block != 1. The native SD2 UNet implementation hard-codes the Hunyuan3D SD2.1 block structure of two ResNet layers and one transformer layer per block.","triggerScenarios":"Loading a UNet config via from_dict where layers_per_block is anything other than 2, or transformer_layers_per_block is anything other than 1 (e.g. deeper UNets with 3 ResNet layers per block).","commonSituations":"Using a community fine-tuned SD2.1 variant with deeper blocks; porting a config from another diffusion framework that uses different layer counts.","solutions":["Set layers_per_block = 2 in the config","Set transformer_layers_per_block = 1 in the config","Use the original Hunyuan3D SD2.1 checkpoint config"],"exampleFix":"// before\nlayers_per_block = 3\ntransformer_layers_per_block = 2\n// after\nlayers_per_block = 2\ntransformer_layers_per_block = 1","handlingStrategy":"validation","validationCode":"assert cfg_dict.get(\"layers_per_block\") == 2 and cfg_dict.get(\"transformer_layers_per_block\", 1) == 1","typeGuard":"def has_hunyuan_block_layout(d: dict) -> bool:\n    return d.get(\"layers_per_block\") == 2 and d.get(\"transformer_layers_per_block\", 1) == 1","tryCatchPattern":null,"preventionTips":["Diff your config against the reference Hunyuan3D config before loading"],"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"}