sgl-project/sglang · error · ValueError

component_attention_backends must use component=backend entr

Error message

component_attention_backends must use component=backend entries

What it means

When --component-attention-backends is given as a plain (non-JSON) string, it is split on commas and each entry must contain '=' mapping a component to a backend name. An entry without '=' cannot be parsed into component=backend.

Source

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

            raise ValueError(
                "component_attention_backends must be a dict or a comma-separated component=backend string"
            )

        try:
            parsed = json.loads(value)
            if not isinstance(parsed, dict):
                raise ValueError
            return parsed
        except (json.JSONDecodeError, ValueError):
            pass

        result: dict[str, str] = {}
        for pair in value.split(","):
            pair = pair.strip()
            if not pair:
                continue
            if "=" not in pair:
                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")

View on GitHub (pinned to 0132848349)

Solutions

1. Use component=backend per entry: 'dit=flash,vae=vanilla'
2. Verify every comma-separated segment contains '='
3. Alternatively pass JSON: '{"dit": "flash"}'

Example fix

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

def valid_pair_string(s: str) -> bool:
    return all('=' in p for p in (x.strip() for x in s.split(',')) if p)

When it happens

Trigger: Passing 'flash' (single backend, no component), or 'dit=flash,faist' (typo'd second pair without '=').

Common situations: Assuming the flag sets a global backend rather than per-component; broken copy-paste of comma lists; stray trailing tokens after a comma.

Related errors

• {option} must use component=value entries
• Component attention backend key must not be empty
• Invalid --warmup-mode {self.warmup_mode!r}; expected one of
• --warmup-num-frames must be a positive integer.
• Invalid threshold_type for topk: {threshold_type}. Choose 'q

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