sgl-project/sglang · warning · DeprecationWarning

head_first is deprecated and will be removed in a future ver

Error message

head_first is deprecated and will be removed in a future version. Please use head_first=False for now instead.

What it means

chunk_gated_delta_rule (FLA gated delta rule chunked kernel) removed head-first tensor layout; the wrapper raises DeprecationWarning (an exception class used as such here) whenever head_first=True is passed. The subsequent rearrange code is dead and never executes.

Source

Thrown at python/sglang/kernels/ops/attention/fla/chunk.py:218

        # for a batch with 4 sequences, `cu_seqlens` with 5 start/end positions are expected
        >>> cu_seqlens = q.new_tensor([0, 2048, 4096, 6144, 8192], dtype=torch.long)
        >>> o_var, ht_var = chunk_gated_delta_rule(
            q, k, v, g, beta,
            initial_state=h0,
            output_final_state=True,
            cu_seqlens=cu_seqlens
        )
    """
    assert q.dtype == k.dtype == v.dtype
    assert (
        q.dtype != torch.float32
    ), "ChunkGatedDeltaRuleFunction does not support float32. Please use bfloat16."
    assert (
        len(beta.shape) == 3
    ), "beta must be of shape [B, T, H] if head_first=False, or [B, H, T] otherwise."

    if head_first:
        raise DeprecationWarning(
            "head_first is deprecated and will be removed in a future version. "
            "Please use head_first=False for now instead."
        )
        q, k, v, beta, g = map(
            lambda x: rearrange(x, "b h t ... -> b t h ..."), (q, k, v, beta, g)
        )
    # if not head_first and q.shape[1] < q.shape[2]:
    #     warnings.warn(
    #         f"Input tensor shape suggests potential format mismatch: seq_len ({q.shape[1]}) < num_heads ({q.shape[2]}). "
    #         "This may indicate the inputs were passed in head-first format [B, H, T, ...] "
    #         "when head_first=False was specified. "
    #         "Please verify your input tensor format matches the expected shape [B, T, H, ...]."
    #     )
    if cu_seqlens is not None:
        if q.shape[0] != 1:
            raise ValueError(
                f"The batch size is expected to be 1 rather than {q.shape[0]} when using `cu_seqlens`."
                f"Please flatten variable-length inputs before processing."

View on GitHub (pinned to 0132848349)

Solutions

1. Pass head_first=False and transpose inputs to [B, T, H, ...]: q = q.transpose(1, 2) etc.
2. Update to the new layout convention throughout your calling code
3. Remove any head_first argument entirely (default is False)

Example fix

# before
out = chunk_gated_delta_rule(q, k, v, beta, g, head_first=True)  # [B,H,T,...]
# after
q, k, v = (t.transpose(1, 2) for t in (q, k, v))  # -> [B,T,H,...]
beta = beta.transpose(1, 2); g = g.transpose(1, 2)
out = chunk_gated_delta_rule(q, k, v, beta, g, head_first=False)

assert not head_first, "head_first removed: pass [B,T,H,...] tensors with head_first=False"

When it happens

Trigger: Calling chunk_gated_delta_rule(..., head_first=True) with tensors laid out [B, H, T, ...] — the old FLA convention.

Common situations: Porting older fla / fla-legacy code or tutorials that used head-first layout; upgrading the fla package where head_first used to be the default; copied snippets from older Gated DeltaRule examples.

Related errors

• The batch size is expected to be 1 rather than {q.shape[0]}
• The number of initial states is expected to be equal to the
• Unsupported input shape {g.shape}, which should be (B, T, H,
• This layer norm doesn't support feature dim >= 64KB.
• Unsupported activation: {self.activation}

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