sgl-project/sglang · error · ValueError

Invalid causality_axis: {causality_axis}

Error message

Invalid causality_axis: {causality_axis}

What it means

LTX2AudioCausalConv2d computes asymmetric padding based on causality_axis and only accepts 'none', 'width', 'width-compatibility', and 'height'. Any other value raises this ValueError during module construction, since no padding scheme is defined for it.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/vaes/ltx_2_audio.py:52

        super().__init__()

        self.causality_axis = causality_axis
        kernel_size = (
            (kernel_size, kernel_size) if isinstance(kernel_size, int) else kernel_size
        )
        dilation = (dilation, dilation) if isinstance(dilation, int) else dilation

        pad_h = (kernel_size[0] - 1) * dilation[0]
        pad_w = (kernel_size[1] - 1) * dilation[1]

        if self.causality_axis == "none":
            padding = (pad_w // 2, pad_w - pad_w // 2, pad_h // 2, pad_h - pad_h // 2)
        elif self.causality_axis in {"width", "width-compatibility"}:
            padding = (pad_w, 0, pad_h // 2, pad_h - pad_h // 2)
        elif self.causality_axis == "height":
            padding = (pad_w // 2, pad_w - pad_w // 2, pad_h, 0)
        else:
            raise ValueError(f"Invalid causality_axis: {causality_axis}")

        self.padding = padding
        self.conv = nn.Conv2d(
            in_channels,
            out_channels,
            kernel_size,
            stride=stride,
            padding=0,
            dilation=dilation,
            groups=groups,
            bias=bias,
        )

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        x = F.pad(x, self.padding)
        return self.conv(x)

View on GitHub (pinned to 0132848349)

Solutions

1. Set causality_axis to one of 'none', 'width', 'width-compatibility', or 'height'
2. Use the exact value from the official LTX-2 audio checkpoint config
3. Upgrade sglang if the checkpoint requires an axis value added in a newer version

Example fix

// before
conv = LTX2AudioCausalConv2d(64, 128, 3, causality_axis='w')

// after
conv = LTX2AudioCausalConv2d(64, 128, 3, causality_axis='width')

VALID_AXES = {'none', 'width', 'width-compatibility', 'height'}
assert causality_axis in VALID_AXES, f'causality_axis must be one of {VALID_AXES}'

def is_valid_causality_axis(axis: str) -> bool:
    return axis in {'none', 'width', 'width-compatibility', 'height'}

When it happens

Trigger: Instantiating LTX2AudioCausalConv2d (or building the LTX-2 audio VAE whose config feeds causality_axis) with a string outside the accepted set — e.g. 'h', 'w', 'time', 'batch', or a typo like 'Height'.

Common situations: Loading an audio-VAE checkpoint with a config using shorthand or renamed axis names; writing a custom causal conv stack and guessing the axis values; version skew where a newer release added an axis (e.g. 'width-compatibility') not present in the installed one.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Unsupported mc_algo {mc_algo}, available: {list(SurfaceExtra
• Unsupported down_block_type: {down_block_type}
• Unsupported time_compression_ratio: {temporal_compression_ra
• Unsupported up_block_type: {up_block_type}
• Unsupported time_compression_ratio: {time_compression_ratio}

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