sgl-project/sglang · error · ValueError

component_attention_backends must be a dict or a comma-separ

Error message

component_attention_backends must be a dict or a comma-separated component=backend string

What it means

--component-attention-backends accepts either a dict (programmatic use) or a string that is JSON or comma-separated component=backend pairs. Passing any other type (int, list, tuple, None-adjacent objects) raises this error before parsing is attempted.

Source

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

            )
        )
        if policy not in RESIDENCY_POLICIES:
            raise ValueError(
                f"unknown residency policy {policy!r} for component "
                f"{component_name!r}, expected one of {RESIDENCY_POLICIES}"
            )
        return prefetch, resident, policy

    @staticmethod
    def _parse_component_attention_backend_map(
        value: dict[str, str] | str | None,
    ) -> dict[str, str]:
        if value is None or value == "":
            return {}
        if isinstance(value, dict):
            return dict(value)
        if not isinstance(value, str):
            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(

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a dict {'dit': 'flash'} directly
2. Or pass a string: 'dit=flash' or '{"dit": "flash"}'
3. Fix the upstream config loader so the field is str or dict

Example fix

# before
args = ServerArgs(component_attention_backends=["dit=flash"])
# after
args = ServerArgs(component_attention_backends={"dit": "flash"})

if not isinstance(backends, (str, dict)) or backends in (None, ''):
    raise TypeError('component_attention_backends must be str or dict')

def is_backend_map_input(v) -> bool:
    return v is None or v == '' or isinstance(v, (str, dict))

When it happens

Trigger: Calling from_cli_args or _normalize_component_attention_backends with component_attention_backends=["dit=flash"] or 3 instead of a dict/str; passing a list of pair-strings programmatically.

Common situations: Programmatic ServerArgs construction where a YAML/JSON config was loaded with a wrong type; passing a list because the CLI appears repeatable; None handling delegated incorrectly.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Component attention backend key must be a string
• cache_dit_params must be a dict, got {type(raw).__name__}.
• Sparse Video Gen 2 attention does not support causal attenti
• {selection_error}{component_suffix}
• Invalid component residency assignment: {value!r}

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