sgl-project/sglang · error · ValueError

Component attention backend key must not be empty

Error message

Component attention backend key must not be empty

What it means

A component-attention-backend entry whose key strips/normalizes to the empty string (e.g. ' ', '-', or '=flash') is rejected because there is no component to assign the backend to.

Source

Thrown at python/sglang/multimodal_gen/runtime/server_args/server_args.py:1138

                raise ValueError(
                    "component_attention_backends must use component=backend entries"
                )
            component, backend = pair.split("=", 1)
            result[component.strip()] = backend.strip()
        return result

    @classmethod
    def _normalize_component_attention_backends(
        cls, value: dict[str, str] | str | None
    ) -> dict[str, str]:
        raw = cls._parse_component_attention_backend_map(value)
        normalized: dict[str, str] = {}
        for component, backend in raw.items():
            if not isinstance(component, str):
                raise ValueError("Component attention backend key must be a string")
            component_name = component.strip().replace("-", "_")
            if not component_name:
                raise ValueError("Component attention backend key must not be empty")
            normalized[component_name] = cls._normalize_attention_backend_name(backend)
        return normalized

    def resolve_component_attention_backend(
        self, *component_names: str | None
    ) -> tuple[AttentionBackendEnum | None, str | None]:
        for component_name in component_names:
            if component_name is None:
                continue
            key = component_name.replace("-", "_")
            fallback_keys = [key]
            if key.endswith("_2"):
                # Secondary two-stage components inherit the base component
                # backend unless explicitly overridden.
                fallback_keys.append(key[:-2])
            for backend_key in fallback_keys:
                backend = self.component_attention_backends.get(backend_key)
                if backend is not None:

View on GitHub (pinned to 0132848349)

Solutions

1. Remove empty component entries from the string/dict
2. Check for keys that are only whitespace or hyphens
3. Validate the map before constructing ServerArgs

Example fix

# before
--component-attention-backends dit=flash,=sdpa
# after
--component-attention-backends dit=flash

assert all(k.strip() and k.strip().replace('-', '_') for k in backends), 'empty component key'

def no_empty_keys(d: dict[str, str]) -> bool:
    return all(k.strip().replace('-', '_') for k in d)

When it happens

Trigger: Passing 'dit=flash,=sdpa' or a dict key of '-' (hyphen-only, which normalize replaces with '_' leaving an empty-ish name), or whitespace-only key.

Common situations: Trailing 'x=' style entries from malformed comma lists; accidental empty key in generated configs.

Related errors

• component_attention_backends must use component=backend entr
• Invalid threshold_type for topk: {threshold_type}. Choose 'q
• Invalid threshold_type: {threshold_type}. Choose 'query_head
• f"Unknown feature map: {feature_map}"
• Missing required argument for SparseVideoGen2Attention: {nam

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