sgl-project/sglang · error · NotImplementedError

AITer backend does not have a metadata builder.

Error message

AITer backend does not have a metadata builder.

What it means

The AITer attention backend's AttentionBackend static method get_builder_cls raises NotImplementedError by design: AITer does not use per-batch attention metadata builders, so requesting one is a programming error in the caller. Note get_metadata_cls returns plain AttentionMetadata.

Source

Thrown at python/sglang/multimodal_gen/runtime/layers/attention/backends/aiter.py:112

    Backend for AITemplate attention implementation.
    """

    @staticmethod
    def get_enum() -> AttentionBackendEnum:
        return AttentionBackendEnum.AITER

    @staticmethod
    def get_impl_cls() -> type["AITerImpl"]:
        return AITerImpl

    @staticmethod
    def get_metadata_cls() -> type["AttentionMetadata"]:
        # AITer backend does not require special metadata.
        return AttentionMetadata

    @staticmethod
    def get_builder_cls() -> type["AttentionMetadataBuilder"]:
        raise NotImplementedError("AITer backend does not have a metadata builder.")


class AITerImpl(AttentionImpl):
    """
    Implementation of attention using AITemplate.
    """

    def __init__(
        self,
        num_heads: int,
        head_size: int,
        softmax_scale: float,
        causal: bool = False,
        num_kv_heads: int | None = None,
        prefix: str = "",
        dropout_p: float = 0.0,
        **extra_impl_args,
    ) -> None:

View on GitHub (pinned to 0132848349)

Solutions

1. Do not call get_builder_cls for AITer; guard with hasattr/try or a backend capability flag before requesting a builder
2. Use get_metadata_cls() (returns base AttentionMetadata) since AITer needs no special metadata
3. If your code path requires a builder, route AITer through a no-op builder like AscendFAMetadataBuilder's pattern or skip metadata building entirely

Example fix

# before
builder = backend.get_builder_cls()()  # crashes for AITer
# after
try:
    builder = backend.get_builder_cls()()
except NotImplementedError:
    builder = None  # AITer needs no metadata builder

try:
    builder = backend.get_builder_cls()()
except NotImplementedError:
    builder = None  # AITer needs no metadata builder

When it happens

Trigger: Calling AITerBackend.get_builder_cls() directly, or generic orchestration code that unconditionally instantiates a metadata builder for every registered backend instead of checking support first.

Common situations: Writing new runtime glue that assumes every backend implements get_builder_cls; refactoring the backend registry; a fallback/dispatch layer that probes all backends' builders at startup.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• AITER Sage backend does not have a metadata builder.
• AITer backend requires num_heads ({num_heads}) to be a multi
• native MXFP8 MoE only supports gated swiglu-oai, got {activa
• AITER Sage attention is not available, please update AITER v
• {type(self).__name__} does not implement packed varlen atten

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