sgl-project/sglang · error · ValueError

T2I adapter residuals are not supported by Hunyuan3D.

Error message

T2I adapter residuals are not supported by Hunyuan3D.

What it means

Raised by the Hunyuan3D SD2.1 UNet forward when down_intrablock_additional_residuals is not None. T2I-Adapter style intra-block residuals are not implemented in this native UNet.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py:829

        self,
        sample: torch.Tensor,
        timestep: torch.Tensor | float | int,
        encoder_hidden_states: torch.Tensor,
        class_labels: torch.Tensor | None = None,
        timestep_cond: torch.Tensor | None = None,
        attention_mask: torch.Tensor | None = None,
        cross_attention_kwargs: dict[str, Any] | None = None,
        added_cond_kwargs: dict[str, torch.Tensor] | None = None,
        down_block_additional_residuals: tuple[torch.Tensor, ...] | None = None,
        mid_block_additional_residual: torch.Tensor | None = None,
        down_intrablock_additional_residuals: tuple[torch.Tensor, ...] | None = None,
        encoder_attention_mask: torch.Tensor | None = None,
        return_dict: bool = True,
    ) -> StableDiffusionUNetOutput | tuple[torch.Tensor]:
        if timestep_cond is not None or added_cond_kwargs is not None:
            raise ValueError("The Hunyuan3D SD2.1 UNet has no added conditioning.")
        if down_intrablock_additional_residuals is not None:
            raise ValueError("T2I adapter residuals are not supported by Hunyuan3D.")
        if (down_block_additional_residuals is None) != (
            mid_block_additional_residual is None
        ):
            raise ValueError(
                "ControlNet down and mid residuals must be provided together."
            )

        attention_mask = self._attention_bias(attention_mask, sample.dtype)
        encoder_attention_mask = self._attention_bias(
            encoder_attention_mask, sample.dtype
        )
        if self.config.center_input_sample:
            sample = 2 * sample - 1.0

        time_embedding = self._time_embedding(sample, timestep)
        if self.class_embedding is not None:
            if class_labels is None:
                raise ValueError("class_labels are required by this UNet.")

View on GitHub (pinned to 0132848349)

Solutions

1. Remove down_intrablock_additional_residuals from the call
2. If using ControlNet, pass down_block_additional_residuals and mid_block_additional_residual instead

Example fix

# before
unet(x, t, encoder_hidden_states=ctx, down_intrablock_additional_residuals=res)
# after
unet(x, t, encoder_hidden_states=ctx, down_block_additional_residuals=down_res, mid_block_additional_residual=mid_res)

if down_intrablock_additional_residuals is not None:
    raise RuntimeError("T2I adapters unsupported; use ControlNet residuals instead")

def is_t2i_free(kwargs: dict) -> bool:
    return kwargs.get("down_intrablock_additional_residuals") is None

When it happens

Trigger: Passing down_intrablock_additional_residuals (a tuple of per-block residuals from a T2I adapter) to forward.

Common situations: Porting a diffusers pipeline that supports T2I-Adapter; feeding adapter outputs that should have gone to the ControlNet-style residual args.

Related errors

• The Hunyuan3D SD2.1 UNet has no added conditioning.
• The native SD2 UNet currently supports only the Hunyuan3D fo
• Hunyuan3D SD2.1 UNet requires four channel stages.
• Hunyuan3D SD2.1 UNet requires two ResNet layers and one tran
• Hunyuan3D SD2.1 checkpoints require linear projection.

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/7cf4254d30fbbda4. Report an issue: GitHub.