sgl-project/sglang · error · ComponentResidencyError

Invalid component residency assignment: {value!r}

Error message

Invalid component residency assignment: {value!r}

What it means

normalize_component_residency accepts assignments as a dict, a single string, or a list of strings. Non-string items inside a list (ints, dicts, None) cannot be parsed as COMPONENT=MODE and raise ComponentResidencyError.

Source

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

    LAYERWISE_OFFLOAD_IMAGE_ENCODER_GROUP,
    LAYERWISE_OFFLOAD_VAE_GROUP,
)


def normalize_component_residency(
    assignments: str | Sequence[str] | Mapping[str, str] | None,
) -> dict[str, str] | None:
    if assignments is None:
        return None

    if isinstance(assignments, Mapping):
        entries = assignments.items()
    else:
        values = [assignments] if isinstance(assignments, str) else assignments
        parsed_entries: list[tuple[str, str]] = []
        for value in values:
            if not isinstance(value, str):
                raise ComponentResidencyError(
                    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):

View on GitHub (pinned to 0132848349)

Solutions

1. Make every element a string of the form COMPONENT=MODE
2. Filter/validate the list to str before passing

Example fix

# before
residency = ["vit=cpu", 42]
# after
residency = ["vit=cpu", "unet=cpu"]

values = assignments if isinstance(assignments, list) else [assignments]
if any(not isinstance(v, str) for v in values):
    raise SystemExit("all residency assignments must be strings")

def all_str(xs) -> bool:
    return all(isinstance(x, str) for x in (xs if isinstance(xs, list) else [xs]))

When it happens

Trigger: Passing a list like ["vit=cpu", 42] or [None] as the component residency value (e.g. from programmatic construction or a parsed config that wasn't all strings).

Common situations: Building the assignment list from JSON/YAML where one element parsed as a non-string; CLI flag reused programmatically with mixed-type input.

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: {raw_selector!r}={ra
• 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/0f301b9de4910e96. Report an issue: GitHub.