sgl-project/sglang · error · ValueError

MPS supports only resident or layerwise-offload component re

Error message

MPS supports only resident or layerwise-offload component residency

What it means

On MPS, component_residency values must be 'resident' or 'layerwise_offload'; other offload modes rely on CUDA-only facilities and are rejected during platform adjustment.

Source

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

        normalized = model_path.lower()
        return any(
            token in normalized
            for token in (
                "lightricks/ltx-2.3",
                "models--lightricks--ltx-2.3",
                "lightricks__ltx-2.3",
            )
        )

    def _adjust_platform_specific(self):
        if current_platform.is_mps():
            if self.num_gpus != 1:
                raise ValueError("MPS currently supports only --num-gpus 1")
            if self.component_residency is not None and any(
                mode not in (RESIDENT, LAYERWISE_OFFLOAD)
                for mode in self.component_residency.values()
            ):
                raise ValueError(
                    "MPS supports only resident or layerwise-offload component "
                    "residency"
                )
            self.use_fsdp_inference = False

    def is_arg_explicitly_set(self, arg_name: str) -> bool:
        return arg_name in self._explicit_arg_names

    def canonical_residency_mode(self, component_name: str) -> str | None:
        """Resolve the canonical selector for one component, if present."""
        return resolve_component_residency_mode(
            component_name, self.component_residency
        )

    def explicit_residency_mode(self, component_name: str) -> str | None:
        """Resolve explicit controls in canonical-to-compatibility priority."""
        mode = self.canonical_residency_mode(component_name)
        if mode is not None:

View on GitHub (pinned to 0132848349)

Solutions

1. Restrict each entry to resident or layerwise_offload on MPS
2. Drop --component-residency to use defaults
3. Run the exotic offload modes on CUDA hardware instead

Example fix

# before
--component-residency dit=block_offload  # on MPS
# after
--component-residency dit=layerwise_offload

ALLOWED = {'resident', 'layerwise_offload'}
if on_mps:
    assert all(m in ALLOWED for m in component_residency.values())

def mps_safe_residency(m: str) -> bool:
    return m in ('resident', 'layerwise_offload')

When it happens

Trigger: --component-residency dit=cycle or any non-{RESIDENT, LAYERWISE_OFFLOAD} mode while running on Apple MPS.

Common situations: Porting CUDA-oriented offload configs (e.g. block/cycle offload) to a Mac; defaults introduced by a shared config that include unsupported modes.

Related errors

• MPS currently supports only --num-gpus 1
• unknown residency policy {policy!r} for component {component
• {feature_name} requires {component_name!r} to be resident; g
• This browser cannot encode H.264 MP4
• H.264 encoder did not return MP4 decoder config

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