sgl-project/sglang · error · ValueError

{feature_name} requires {component_name!r} to be resident; g

Error message

{feature_name} requires {component_name!r} to be resident; got {configured_mode!r} from --component-residency

What it means

require_component_resident() is called by features (native load, model load, NVFP4 fallback, offload-mode adjustment) that need a component fully resident in GPU memory. If --component-residency configured a non-resident mode for that component, the feature aborts.

Source

Thrown at python/sglang/multimodal_gen/runtime/server_args/server_args.py:1545

        if is_vae_component_name(component_name):
            return COMPONENT_OFFLOAD if self.vae_cpu_offload else RESIDENT
        return RESIDENT

    def should_cpu_offload_component(self, component_name: str) -> bool:
        return self.residency_mode(component_name) == COMPONENT_OFFLOAD

    def should_start_component_on_cpu(self, component_name: str) -> bool:
        return self.residency_mode(component_name) in (
            COMPONENT_OFFLOAD,
            LAYERWISE_OFFLOAD,
        )

    def require_component_resident(
        self, component_name: str, *, feature_name: str
    ) -> None:
        configured_mode = self.canonical_residency_mode(component_name)
        if configured_mode is not None and configured_mode != RESIDENT:
            raise ValueError(
                f"{feature_name} requires {component_name!r} to be resident; "
                f"got {configured_mode!r} from --component-residency"
            )
        self._required_resident_components.add(component_name)

    def should_use_fsdp_for_component(self, component_name: str) -> bool:
        return bool(
            self.use_fsdp_inference
            and component_name not in self._fsdp_disabled_components
            and self.residency_mode(component_name) == RESIDENT
        )

    def disable_fsdp_for_component(self, component_name: str) -> None:
        self._fsdp_disabled_components.add(component_name)

    def record_component_layerwise_capability(
        self, component_name: str, *, supported: bool
    ) -> None:

View on GitHub (pinned to 0132848349)

Solutions

1. Set the component to resident: --component-residency dit=resident (or remove the override)
2. Disable the feature that requires residency (e.g. the NVFP4 fallback / offload-adjustment path)
3. Free VRAM another way (smaller batch, shorter seqs) so resident mode fits

Example fix

# before
--component-residency dit=layerwise_offload --load-native
# after
--component-residency dit=resident --load-native

mode = args.canonical_residency_mode('dit')
assert mode is None or mode == 'resident', f'feature needs dit resident, got {mode}'

When it happens

Trigger: Enabling e.g. NVFP4 quantization fallback or a native-load path while --component-residency dit=layerwise_offload; the feature then calls require_component_resident('dit', feature_name=...).

Common situations: Combining quantized-load paths with layerwise/block offload to save VRAM; flags added independently by different team members; defaults flipped to offload under memory pressure.

Related errors

• unknown residency policy {policy!r} for component {component
• MPS supports only resident or layerwise-offload component re
• This browser cannot encode H.264 MP4
• H.264 encoder did not return MP4 decoder config
• This browser does not support gzip stream decoding

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