sgl-project/sglang · error · ComponentResidencyError

Component {component_name!r} resolved to component-offload,

Error message

Component {component_name!r} resolved to component-offload, but it was loaded as an FSDP-managed module

What it means

If the resolved residency mode for a component is component-offload but the module was loaded as FSDP-managed, the strategy builder raises: FSDP sharding already manages parameter placement, so per-component CPU offload on top of it is not supported.

Source

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

    _stage_name_mapping: Mapping[str, ComponentResidencyStage]
    component_residency_strategies: MutableMapping[str, "ComponentResidencyStrategy"]


def build_component_residency_strategy(
    component_name: str,
    module: nn.Module,
    server_args: ServerArgs,
) -> ComponentResidencyStrategy:
    residency_mode = server_args.residency_mode(component_name)
    if is_layerwise_offloaded_module(module):
        return LayerwiseOffloadStrategy()
    if residency_mode == LAYERWISE_OFFLOAD:
        raise ComponentResidencyError(
            f"Component {component_name!r} resolved to layerwise-offload, but its "
            "loaded module did not enable layerwise offload"
        )
    if residency_mode == COMPONENT_OFFLOAD and is_fsdp_managed_module(module):
        raise ComponentResidencyError(
            f"Component {component_name!r} resolved to component-offload, but it "
            "was loaded as an FSDP-managed module"
        )
    if (
        not current_platform.is_mps()
        and not is_fsdp_managed_module(module)
        and residency_mode == COMPONENT_OFFLOAD
    ):
        return ComponentOffloadStrategy()
    return ResidentStrategy()


class ComponentResidencyManager:
    """Coordinate component placement over a sequential request timeline."""

    def __init__(
        self, pipeline: ComponentResidencyPipeline, server_args: ServerArgs
    ) -> None:

View on GitHub (pinned to 0132848349)

Solutions

1. Remove the component-offload assignment for FSDP-managed components (let FSDP handle placement)
2. Switch those components to layerwise-offload or gpu mode in the residency config
3. Disable FSDP if per-component CPU offload is the hard requirement

Example fix

# before
--enable-fsdp --component-residency *=component-offload
# after
--enable-fsdp --component-residency *=layerwise-offload

from sglang.multimodal_gen.runtime.managers.memory_managers.component_manager import is_fsdp_managed_module
if is_fsdp_managed_module(module):
    assert mode != "component-offload", "FSDP modules cannot use component-offload"

def allows_component_offload(module) -> bool:
    return not is_fsdp_managed_module(module)

When it happens

Trigger: residency_mode == COMPONENT_OFFLOAD and is_fsdp_managed_module(module) is true — e.g. running with FSDP enabled and a residency config assigning "*=component-offload" or a specific FSDP-wrapped component to component-offload.

Common situations: Enabling FSDP for multi-GPU sharding while keeping a pre-existing --component-residency / legacy CPU-offload flag that worked in the non-FSDP setup.

Related errors

• Component {component_name!r} resolved to layerwise-offload,
• Invalid component residency assignment: {value!r}
• Component residency must use COMPONENT=MODE, got {assignment
• Invalid component residency assignment: {raw_selector!r}={ra
• Component residency selector cannot be empty

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