What causes "Unexpected swizzle shift – want S==3 for M==4" in sgl-project/sglang?

Use the canonical swizzle atoms produced by cute (e.g. via make_cute_layout / standard tile atoms) rather than building Swizzle objects by hand.

sgl-project/sglang · error · ValueError

Unexpected swizzle shift – want S==3 for M==4

Error message

Unexpected swizzle shift – want S==3 for M==4

What it means

_layout_type maps a cute.Swizzle< B, M, S > triple to a UMMA shared-memory layout type. For M==4 the shift field S must be 3 (Swizzle<*,4,3> is the only legal family); other shifts raise this ValueError.

Source

Thrown at python/sglang/kernels/ops/attention/flash_attn/cute/mma_sm100_desc.py:206

    SWIZZLE_NONE = 0  # (a.k.a. “INTERLEAVE” in older docs)
    SWIZZLE_128B_BASE32B = 1
    SWIZZLE_128B = 2
    SWIZZLE_64B = 4
    SWIZZLE_32B = 6
    # values 3,5,7 are reserved / illegal for UMMA


# ---------------------------------------------------------------------------
#  Helpers – figure out the SWIZZLE_* family from the tensor layout
# ---------------------------------------------------------------------------


def _layout_type(swizzle: cute.Swizzle) -> LayoutType:
    B, M, S = swizzle.num_bits, swizzle.num_base, swizzle.num_shift

    if M == 4:  # Swizzle<*,4,3>
        if S != 3:
            raise ValueError("Unexpected swizzle shift – want S==3 for M==4")
        return {
            0: LayoutType.SWIZZLE_NONE,
            1: LayoutType.SWIZZLE_32B,
            2: LayoutType.SWIZZLE_64B,
            3: LayoutType.SWIZZLE_128B,
        }[
            B
        ]  # KeyError ⇒ invalid B→ raise
    if M == 5:  # Swizzle<2,5,2> (the only legal triple for M==5)
        if (B, S) != (2, 2):
            raise ValueError("Only Swizzle<2,5,2> supported for 128B_BASE32B")
        return LayoutType.SWIZZLE_128B_BASE32B

    # Any other (M,B,S) triple is not a UMMA-legal shared-memory layout
    raise ValueError("Unsupported swizzle triple for UMMA smem descriptor")


def make_smem_desc_base(

View on GitHub (pinned to 0132848349)

Solutions

Use the canonical swizzle atoms produced by cute (e.g. via make_cute_layout / standard tile atoms) rather than building Swizzle objects by hand.
Set num_shift=3 whenever num_base==4.
Prefer smem_desc_base_from_tensor over manual layout+swizzle plumbing.

Defensive patterns

Strategy: validation

Validate before calling

assert swizzle.num_base != 4 or swizzle.num_shift == 3

Prevention

Never hand-edit swizzle fields; copy atoms from cute's canonical constructors.
Centralize swizzle constants instead of re-deriving them per site.

When it happens

Trigger: Calling make_smem_desc_base with a swizzle whose num_base is 4 but num_shift != 3, e.g. Swizzle<3,4,2> constructed manually or from a copied layout that was mutated.

Common situations: Hand-constructing swizzled shared-memory layouts instead of using the canonical atoms; modifying an existing atom's shift field while tuning.

Related errors

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