sgl-project/sglang · error · ComponentResidencyError

Invalid component residency assignment: {raw_selector!r}={ra

Error message

Invalid component residency assignment: {raw_selector!r}={raw_mode!r}

What it means

When assignments are given as a dict, both the selector key and the mode value must be strings; non-string keys or values (e.g. int keys from JSON with numeric component ids, or None values) raise ComponentResidencyError.

Source

Thrown at python/sglang/multimodal_gen/runtime/managers/memory_managers/component_residency.py:84

                    f"Invalid component residency assignment: {value!r}"
                )
            for assignment in value.split(","):
                assignment = assignment.strip()
                if not assignment:
                    continue
                if "=" not in assignment:
                    raise ComponentResidencyError(
                        "Component residency must use COMPONENT=MODE, got "
                        f"{assignment!r}"
                    )
                selector, mode = assignment.split("=", 1)
                parsed_entries.append((selector, mode))
        entries = parsed_entries

    normalized: dict[str, str] = {}
    for raw_selector, raw_mode in entries:
        if not isinstance(raw_selector, str) or not isinstance(raw_mode, str):
            raise ComponentResidencyError(
                "Invalid component residency assignment: "
                f"{raw_selector!r}={raw_mode!r}"
            )
        selector = raw_selector.strip().replace("-", "_").lower()
        mode = raw_mode.strip().replace("_", "-").lower()
        if not selector:
            raise ComponentResidencyError(
                "Component residency selector cannot be empty"
            )
        if mode not in COMPONENT_RESIDENCY_MODES:
            expected = ", ".join(sorted(COMPONENT_RESIDENCY_MODES))
            raise ComponentResidencyError(
                f"Invalid component residency mode {raw_mode!r} for "
                f"{selector!r}; expected one of: {expected}"
            )
        normalized[selector] = mode

    return normalized or None

View on GitHub (pinned to 0132848349)

Solutions

1. Coerce all keys and values to strings before building the dict
2. Drop entries whose mode is None instead of storing None

Example fix

# before
residency = {4096: "cpu", "vit": None}
# after
residency = {"4096": "cpu"}

if any(not isinstance(k, str) or not isinstance(v, str) for k, v in d.items()):
    raise SystemExit("residency dict keys and values must be strings")

def is_str_str_dict(d) -> bool:
    return all(isinstance(k, str) and isinstance(v, str) for k, v in d.items())

When it happens

Trigger: Passing a dict like {4096: "cpu"} or {"vit": None} to normalize_component_residency / the _normalize_component_residency entry point.

Common situations: Programmatically building the mapping from data that wasn't coerced to strings (numeric model/component IDs, optional fields left as None).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid component residency assignment: {value!r}
• must be list or null; got {type(v).__name__}
• elements must be int or list; got {type(v[0]).__name__}
• Unknown type: {type(other)}
• 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/a6d83943eccc32fa. Report an issue: GitHub.