sgl-project/sglang · warning · DeprecationWarning

VisionAttention(head_size=...) is deprecated; use head_dim=.

Error message

VisionAttention(head_size=...) is deprecated; use head_dim=...

What it means

DeprecationWarning raised in VisionAttention.__init__: the constructor argument `head_size` was renamed to `head_dim`. Passing head_size still works (it is popped from kwargs and mapped to head_dim) but warns and will be removed.

Source

Thrown at python/sglang/srt/layers/attention/vision.py:1067

        qkv_bias: bool = True,
        qk_normalization: bool = False,
        qk_normalization_by_head_size: bool = False,
        layer_norm_eps: float = 1e-06,
        customized_position_embedding_applier: Callable[
            [torch.Tensor, torch.Tensor, Any, Any], Tuple[torch.Tensor, torch.Tensor]
        ] = None,
        use_data_parallel: bool = False,
        use_dp_attention_reduce: bool = False,
        aux_stream: Optional[torch.cuda.Stream] = None,
        workspace_buffer: Optional[torch.Tensor] = None,
        use_sink: bool = False,
        window_size: Tuple[int, int] = (-1, -1),
        **kwargs,
    ):
        super().__init__()
        if head_dim is None and "head_size" in kwargs:
            head_dim = kwargs.pop("head_size")
            warnings.warn(
                "VisionAttention(head_size=...) is deprecated; use head_dim=...",
                DeprecationWarning,
                stacklevel=2,
            )
        self.tp_size = 1 if use_data_parallel else get_parallel().attn_tp_size
        self.tp_rank = 0 if use_data_parallel else get_parallel().attn_tp_rank
        self.dropout = dropout
        num_kv_heads = num_kv_heads if num_kv_heads is not None else num_heads
        self.head_size = head_dim if head_dim is not None else embed_dim // num_heads
        self.softmax_scale = softmax_scale
        self.hidden_size_per_attention_head = dist_utils.divide(
            projection_size, num_heads
        )
        self.num_attention_heads_per_partition = dist_utils.divide(
            num_dummy_heads + num_heads, self.tp_size
        )
        self.num_attention_kv_heads_per_partition = dist_utils.divide(
            num_dummy_heads + num_kv_heads, self.tp_size

View on GitHub (pinned to 0132848349)

Solutions

1. Rename the keyword argument to head_dim in the VisionAttention(...) call
2. Update any config-to-kwarg mapping code that injects head_size
3. Remove other deprecated kwargs from the same call to avoid future breaks

Example fix

# before
attn = VisionAttention(head_size=72, ...)
# after
attn = VisionAttention(head_dim=72, ...)

kwargs.pop("head_size", None) is None or (_ for _ in ()).throw(ValueError("use head_dim"))

def uses_vision_attn_new_api() -> bool:
    import inspect
    from sglang.srt.layers.attention.vision import VisionAttention
    return "head_dim" in inspect.signature(VisionAttention.__init__).parameters

When it happens

Trigger: Constructing VisionAttention(...) with head_size=N (common when loading checkpoints or instantiating vision towers copied from older code), which triggers the kwargs fallback branch.

Common situations: Vision-language model implementations (e.g. custom ViT towers) written before the argument rename; quantized/CPU configs or HF config plumbing passing head_size through kwargs.

Related errors

• sglang.srt.layers.attention.nsa.dequant_k_cache is deprecate
• sglang.srt.layers.attention.nsa.index_buf_accessor is deprec
• sglang.srt.layers.attention.nsa.nsa_backend_mtp_precompute i
• sglang.srt.layers.attention.nsa.nsa_indexer is deprecated; u
• sglang.srt.layers.attention.nsa.quant_k_cache is deprecated;

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