sgl-project/sglang · error · ValueError

MiniMax-H3 on MPS requires synchronous layerwise offload for

Error message

MiniMax-H3 on MPS requires synchronous layerwise offload for {missing_components}; pass --layerwise-offload-components transformer text_encoder video_vae audio_vae

What it means

MiniMax-H3 on Apple MPS cannot fit all components in unified memory with async execution, so the pipeline requires synchronous layerwise offload for transformer, text_encoder, video_vae, and audio_vae. validate_server_args checks server_args.residency_mode(component) == LAYERWISE_OFFLOAD for each and raises listing the missing ones if any differ.

Source

Thrown at python/sglang/multimodal_gen/configs/pipeline_configs/minimax_h3.py:242

            )

    def validate_server_args(self, server_args) -> None:
        # Reject known-inexact VAE modes before any large component download.
        self.vae_config.resolved_parallel_decode_mode()
        if current_platform.is_mps():
            required_components = (
                "transformer",
                "text_encoder",
                "video_vae",
                "audio_vae",
            )
            missing_components = [
                component
                for component in required_components
                if server_args.residency_mode(component) != LAYERWISE_OFFLOAD
            ]
            if missing_components:
                raise ValueError(
                    "MiniMax-H3 on MPS requires synchronous layerwise offload for "
                    f"{missing_components}; pass --layerwise-offload-components "
                    "transformer text_encoder video_vae audio_vae"
                )
            if server_args.enable_torch_compile:
                raise ValueError(
                    "MiniMax-H3 MPS execution does not support torch.compile; "
                    "pass --enable-torch-compile false"
                )
        selected_backend = self.resolve_transformer_attention_backend(server_args)
        if (
            int(server_args.ring_degree or 1) > 1
            and selected_backend is not AttentionBackendEnum.FA
        ):
            raise ValueError(
                "MiniMax-H3 ring parallelism requires the FlashAttention "
                "backend for the transformer"
            )

View on GitHub (pinned to 0132848349)

Solutions

1. Launch with --layerwise-offload-components transformer text_encoder video_vae audio_vae
2. Ensure every one of the four listed components resolves to LAYERWISE_OFFLOAD, not just some (the error names the missing ones)
3. If full offload is unacceptable, use a CUDA/H200 host instead of MPS

Example fix

# before
python -m sglang.launch_server --model MiniMax-H3 --device mps

# after
python -m sglang.launch_server --model MiniMax-H3 --device mps \
  --layerwise-offload-components transformer text_encoder video_vae audio_vae

required = ["transformer", "text_encoder", "video_vae", "audio_vae"]
missing = [c for c in required if server_args.residency_mode(c) != LAYERWISE_OFFLOAD]
assert not missing, missing

When it happens

Trigger: Running the MiniMax-H3 server on an MPS device without passing --layerwise-offload-components transformer text_encoder video_vae audio_vae (or with only a subset of the components in layerwise-offload mode).

Common situations: Local development on Apple Silicon Macs; users porting CUDA launch flags directly to MPS; partial offload flags copied from another model's recipe.

Related errors

• MiniMax-H3 MPS execution does not support torch.compile; pas
• MiniMax-H3 ring parallelism requires the FlashAttention back
• Serialized W4A4 checkpoints are not supported on MPS
• MiniMax H3 AdaLN cache max_plan_width must be positive; set
• MiniMax H3 Qwen3-VL encoders smaller than 32B require --comp

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