{"record":{"id":"3aa06103ad94657a","repo":"sgl-project/sglang","slug":"hunyuan3d-sd2-1-unet-requires-four-channel-stages","errorCode":null,"errorMessage":"Hunyuan3D SD2.1 UNet requires four channel stages.","messagePattern":"Hunyuan3D SD2\\.1 UNet requires four channel stages\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py","lineNumber":93,"sourceCode":"        expected_down = (\n            \"CrossAttnDownBlock2D\",\n            \"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    *,","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py#L75-L111","documentation":"Raised by StableDiffusionUNetConfig.validate() during from_dict when the UNet config's block_out_channels or attention_head_dim lists do not each have exactly 4 entries. The native SD2.1 UNet implementation only supports the Hunyuan3D four-level channel-stage layout, so any config deviating from 4 stages is rejected.","triggerScenarios":"Loading a StableDiffusion 2.1 UNet config (from_dict) where len(block_out_channels) != 4 or len(attention_head_dim) != 4 — e.g. a 3-stage or 5-stage custom UNet config dict.","commonSituations":"Pointing the loader at a non-Hunyuan3D SD2 checkpoint or a modified UNet with extra/removed channel stages; hand-editing the config JSON and dropping a channel entry.","solutions":["Set block_out_channels to exactly 4 values (e.g. [320, 640, 1280, 1280])","Set attention_head_dim to exactly 4 values matching the stages (e.g. [5, 10, 20, 20])","Use a checkpoint matching the Hunyuan3D SD2.1 architecture instead of an arbitrary SD2 UNet"],"exampleFix":"// before\nblock_out_channels = [320, 640, 1280]\nattention_head_dim = [5, 10, 20]\n// after\nblock_out_channels = [320, 640, 1280, 1280]\nattention_head_dim = [5, 10, 20, 20]","handlingStrategy":"validation","validationCode":"cfg_dict = {...}\nassert len(cfg_dict[\"block_out_channels\"]) == 4 and len(cfg_dict[\"attention_head_dim\"]) == 4, \"need 4 channel stages\"","typeGuard":"def is_valid_sd2_unet_config(d: dict) -> bool:\n    return len(d.get(\"block_out_channels\", [])) == 4 and len(d.get(\"attention_head_dim\", [])) == 4","tryCatchPattern":null,"preventionTips":["Validate config lists before calling from_dict","Pin to the official Hunyuan3D SD2.1 config file"],"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"}