sgl-project/sglang · error · ComponentResidencyError

Invalid component residency mode {raw_mode!r} for {selector!

Error message

Invalid component residency mode {raw_mode!r} for {selector!r}; expected one of: {expected}

What it means

The mode part of COMPONENT=MODE must be one of the recognized COMPONENT_RESIDENCY_MODES; anything else is rejected with a message listing the valid modes (after normalizing '_' to '-').

Source

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

                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)
    if selector == LAYERWISE_OFFLOAD_TEXT_ENCODER_GROUP:
        return is_text_encoder_component_name(component_name)
    if selector == LAYERWISE_OFFLOAD_IMAGE_ENCODER_GROUP:
        return is_image_encoder_component_name(component_name)
    if selector == LAYERWISE_OFFLOAD_VAE_GROUP:

View on GitHub (pinned to 0132848349)

Solutions

1. Use one of the modes listed in the error message exactly
2. Check the COMPONENT_RESIDENCY_MODES constant in component_residency.py for your installed version's valid modes

Example fix

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

from sglang.multimodal_gen.runtime.managers.memory_managers.component_residency import COMPONENT_RESIDENCY_MODES
for tok in s.split(","):
    if "=" not in tok: continue
    mode = tok.split("=", 1)[1].strip().replace("_", "-").lower()
    if mode not in COMPONENT_RESIDENCY_MODES:
        raise SystemExit(f"bad mode {mode!r}; valid: {sorted(COMPONENT_RESIDENCY_MODES)}")

def is_valid_mode(mode: str) -> bool:
    return mode.strip().replace("_", "-").lower() in COMPONENT_RESIDENCY_MODES

When it happens

Trigger: An assignment like "vit=cp" (typo), "vit=CPU!" or "vit=host" where the normalized mode isn't in COMPONENT_RESIDENCY_MODES (e.g. cpu, gpu, layerwise-offload, component-offload).

Common situations: Typos and case/separator variants (mostly auto-normalized); using mode names from a different library version where the mode set changed; guessing mode names instead of checking docs.

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
• Component residency selector cannot be empty
• 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/949e82a4cb21e71a. Report an issue: GitHub.