sgl-project/sglang · error · ComponentResidencyError

Component residency selector cannot be empty

Error message

Component residency selector cannot be empty

What it means

After stripping and normalization (hyphens to underscores), a component selector that becomes empty — e.g. "", "-", "_" — is rejected because it would match nothing meaningfully.

Source

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

                    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


def component_residency_selector_matches(component_name: str, selector: str) -> bool:
    if selector == LAYERWISE_OFFLOAD_ALL_COMPONENTS:
        return True
    if selector == LAYERWISE_OFFLOAD_DIT_GROUP:
        return is_dit_component_name(component_name)

View on GitHub (pinned to 0132848349)

Solutions

1. Provide a real component or group selector before '='
2. Audit the residency string for empty tokens between commas

Example fix

# before
--component-residency =cpu
# after
--component-residency vit=cpu

for tok in s.split(","):
    sel = tok.split("=", 1)[0].strip().replace("-", "_").lower()
    if tok.strip() and ("=" not in tok or not sel):
        raise SystemExit(f"empty selector in {tok!r}")

When it happens

Trigger: An assignment like "=cpu", "-=cpu", or a comma-only string ",," that yields an empty selector before '='.

Common situations: Malformed shell quoting producing an empty token; programmatic string building joining empty parts; stray "=mode" entries after removing a component name.

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

• Component residency must use COMPONENT=MODE, got {assignment
• Invalid component residency mode {raw_mode!r} for {selector!
• This browser cannot encode H.264 MP4
• H.264 encoder did not return MP4 decoder config
• delta payload size mismatch: expected ${expectedSize}, got $

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