{"record":{"id":"c521cf75883ba280","repo":"sgl-project/sglang","slug":"head-first-is-deprecated-and-will-be-removed-in-a","errorCode":null,"errorMessage":"head_first is deprecated and will be removed in a future version. Please use head_first=False for now instead.","messagePattern":"head_first is deprecated and will be removed in a future version\\. Please use head_first=False for now instead\\.","errorType":"exception","errorClass":"DeprecationWarning","httpStatus":null,"severity":"warning","filePath":"python/sglang/kernels/ops/attention/fla/chunk.py","lineNumber":218,"sourceCode":"        # for a batch with 4 sequences, `cu_seqlens` with 5 start/end positions are expected\n        >>> cu_seqlens = q.new_tensor([0, 2048, 4096, 6144, 8192], dtype=torch.long)\n        >>> o_var, ht_var = chunk_gated_delta_rule(\n            q, k, v, g, beta,\n            initial_state=h0,\n            output_final_state=True,\n            cu_seqlens=cu_seqlens\n        )\n    \"\"\"\n    assert q.dtype == k.dtype == v.dtype\n    assert (\n        q.dtype != torch.float32\n    ), \"ChunkGatedDeltaRuleFunction does not support float32. Please use bfloat16.\"\n    assert (\n        len(beta.shape) == 3\n    ), \"beta must be of shape [B, T, H] if head_first=False, or [B, H, T] otherwise.\"\n\n    if head_first:\n        raise DeprecationWarning(\n            \"head_first is deprecated and will be removed in a future version. \"\n            \"Please use head_first=False for now instead.\"\n        )\n        q, k, v, beta, g = map(\n            lambda x: rearrange(x, \"b h t ... -> b t h ...\"), (q, k, v, beta, g)\n        )\n    # if not head_first and q.shape[1] < q.shape[2]:\n    #     warnings.warn(\n    #         f\"Input tensor shape suggests potential format mismatch: seq_len ({q.shape[1]}) < num_heads ({q.shape[2]}). \"\n    #         \"This may indicate the inputs were passed in head-first format [B, H, T, ...] \"\n    #         \"when head_first=False was specified. \"\n    #         \"Please verify your input tensor format matches the expected shape [B, T, H, ...].\"\n    #     )\n    if cu_seqlens is not None:\n        if q.shape[0] != 1:\n            raise ValueError(\n                f\"The batch size is expected to be 1 rather than {q.shape[0]} when using `cu_seqlens`.\"\n                f\"Please flatten variable-length inputs before processing.\"","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/attention/fla/chunk.py#L200-L236","documentation":"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.","triggerScenarios":"Calling chunk_gated_delta_rule(..., head_first=True) with tensors laid out [B, H, T, ...] — the old FLA convention.","commonSituations":"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.","solutions":["Pass head_first=False and transpose inputs to [B, T, H, ...]: q = q.transpose(1, 2) etc.","Update to the new layout convention throughout your calling code","Remove any head_first argument entirely (default is False)"],"exampleFix":"# before\nout = chunk_gated_delta_rule(q, k, v, beta, g, head_first=True)  # [B,H,T,...]\n# after\nq, k, v = (t.transpose(1, 2) for t in (q, k, v))  # -> [B,T,H,...]\nbeta = beta.transpose(1, 2); g = g.transpose(1, 2)\nout = chunk_gated_delta_rule(q, k, v, beta, g, head_first=False)","handlingStrategy":"validation","validationCode":"assert not head_first, \"head_first removed: pass [B,T,H,...] tensors with head_first=False\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Adopt [B, T, H, ...] layout everywhere; treat head_first=True as a migration TODO","Grep for head_first=True when upgrading fla-based code"],"tags":["fla","gated-delta-rule","deprecation","tensor-layout"],"backgroundTag":"deprecated-api-removed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}