sgl-project/sglang · error · ValueError

subsampling_conv_chunking_factor should be -1, 1, or a power

Error message

subsampling_conv_chunking_factor should be -1, 1, or a power of 2

What it means

ConvSubsampling's chunked-convolution memory optimization parameter subsampling_conv_chunking_factor only accepts -1 (disabled), 1, or powers of 2. Odd values other than 1 fail the check and raise ValueError because chunk sizes must evenly divide the strided conv stacks.

Source

Thrown at python/sglang/srt/models/phi4mm_utils.py:1113

        self._feat_out = feat_out

        if subsampling_factor % 2 != 0:
            raise ValueError("Sampling factor should be a multiply of 2!")
        self._sampling_num = int(math.log(subsampling_factor, 2))
        self.subsampling_factor = subsampling_factor
        self.is_causal = is_causal
        self.subsampling_causal_cond = subsampling in (
            "dw_striding",
            "striding",
            "striding_conv1d",
        )

        if (
            subsampling_conv_chunking_factor != -1
            and subsampling_conv_chunking_factor != 1
            and subsampling_conv_chunking_factor % 2 != 0
        ):
            raise ValueError(
                "subsampling_conv_chunking_factor should be -1, 1, or a " "power of 2"
            )
        self.subsampling_conv_chunking_factor = subsampling_conv_chunking_factor

        in_channels = 1
        layers = []

        if subsampling == "dw_striding":
            self._stride = 2
            self._kernel_size = 3
            self._ceil_mode = False

            if self.is_causal:
                self._left_padding = self._kernel_size - 1
                self._right_padding = self._stride - 1
                self._max_cache_len = subsampling_factor + 1
            else:
                self._left_padding = (self._kernel_size - 1) // 2

View on GitHub (pinned to 0132848349)

Solutions

1. Use -1 to disable chunking (default, safest)
2. Use 1 or a power of 2 (2, 4, 8, ...) as the chunking factor
3. Verify the value if it comes from a serialized or programmatically computed config

Example fix

# before
ConvSubsampling(..., subsampling_conv_chunking_factor=6)  # ValueError
# after
ConvSubsampling(..., subsampling_conv_chunking_factor=4)

v = subsampling_conv_chunking_factor
assert v == -1 or v == 1 or (v > 0 and v % 2 == 0), "must be -1, 1, or power of 2"

def is_valid_chunking_factor(v: int) -> bool:
    return v in (-1, 1) or (v > 0 and (v & (v - 1)) == 0)

When it happens

Trigger: Constructing ConvSubsampling with subsampling_conv_chunking_factor set to 3, 5, 6, or any non-power-of-two > 1.

Common situations: Tuning memory usage during long-audio inference and picking an arbitrary chunk factor; porting configs from NeMo where the default is -1; env-driven overrides injecting odd values.

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

• Sampling factor should be a multiply of 2!
• audio_out_channels must be divisible by tp_size for TP-shard
• projection_cls = {projection_cls}, not implemented
• audio_projection_mode = {audio_projection_mode} not implemen
• Unsupported activation type {self.glu_act}

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