{"record":{"id":"164a221e0a18aabf","repo":"sgl-project/sglang","slug":"controlnet-down-and-mid-residuals-must-be-provided","errorCode":null,"errorMessage":"ControlNet down and mid residuals must be provided together.","messagePattern":"ControlNet down and mid residuals must be provided together\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py","lineNumber":833,"sourceCode":"        class_labels: torch.Tensor | None = None,\n        timestep_cond: torch.Tensor | None = None,\n        attention_mask: torch.Tensor | None = None,\n        cross_attention_kwargs: dict[str, Any] | None = None,\n        added_cond_kwargs: dict[str, torch.Tensor] | None = None,\n        down_block_additional_residuals: tuple[torch.Tensor, ...] | None = None,\n        mid_block_additional_residual: torch.Tensor | None = None,\n        down_intrablock_additional_residuals: tuple[torch.Tensor, ...] | None = None,\n        encoder_attention_mask: torch.Tensor | None = None,\n        return_dict: bool = True,\n    ) -> StableDiffusionUNetOutput | tuple[torch.Tensor]:\n        if timestep_cond is not None or added_cond_kwargs is not None:\n            raise ValueError(\"The Hunyuan3D SD2.1 UNet has no added conditioning.\")\n        if down_intrablock_additional_residuals is not None:\n            raise ValueError(\"T2I adapter residuals are not supported by Hunyuan3D.\")\n        if (down_block_additional_residuals is None) != (\n            mid_block_additional_residual is None\n        ):\n            raise ValueError(\n                \"ControlNet down and mid residuals must be provided together.\"\n            )\n\n        attention_mask = self._attention_bias(attention_mask, sample.dtype)\n        encoder_attention_mask = self._attention_bias(\n            encoder_attention_mask, sample.dtype\n        )\n        if self.config.center_input_sample:\n            sample = 2 * sample - 1.0\n\n        time_embedding = self._time_embedding(sample, timestep)\n        if self.class_embedding is not None:\n            if class_labels is None:\n                raise ValueError(\"class_labels are required by this UNet.\")\n            time_embedding = time_embedding + self.class_embedding(class_labels).to(\n                sample.dtype\n            )\n","sourceCodeStart":815,"sourceCodeEnd":851,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py#L815-L851","documentation":"Raised by the Hunyuan3D SD2.1 UNet forward when exactly one of down_block_additional_residuals and mid_block_additional_residual is provided. ControlNet outputs come as a set of down-block residuals plus one mid-block residual; supplying only one side would misalign the residual additions.","triggerScenarios":"Passing down_block_additional_residuals without mid_block_additional_residual, or vice versa.","commonSituations":"Running a ControlNet whose down/residual list was sliced incorrectly, or forgetting to forward controlnet_res[0] and controlnet_res[-1] together.","solutions":["Pass both down_block_additional_residuals and mid_block_additional_residual (or neither)","Check the ControlNet forward returns and feed [:-1] to down and [-1] to mid"],"exampleFix":"# before\nunet(x, t, encoder_hidden_states=ctx, down_block_additional_residuals=res[:-1])\n# after\nunet(x, t, encoder_hidden_states=ctx, down_block_additional_residuals=res[:-1], mid_block_additional_residual=res[-1])","handlingStrategy":"type-guard","validationCode":"assert (down_res is None) == (mid_res is None), \"ControlNet residuals must come in pairs\"","typeGuard":"def controlnet_residuals_paired(down, mid) -> bool:\n    return (down is None) == (mid is None)","tryCatchPattern":null,"preventionTips":["Feed res[:-1] to down and res[-1] to mid in one expression"],"tags":["controlnet","argument-pairing","unet"],"backgroundTag":"invalid-argument-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}