{"record":{"id":"ce233dabfb9c1b44","repo":"sgl-project/sglang","slug":"minimax-h3-on-mps-requires-synchronous-layerwise-o","errorCode":null,"errorMessage":"MiniMax-H3 on MPS requires synchronous layerwise offload for {missing_components}; pass --layerwise-offload-components transformer text_encoder video_vae audio_vae","messagePattern":"MiniMax-H3 on MPS requires synchronous layerwise offload for (.+?); pass --layerwise-offload-components transformer text_encoder video_vae audio_vae","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/configs/pipeline_configs/minimax_h3.py","lineNumber":242,"sourceCode":"            )\n\n    def validate_server_args(self, server_args) -> None:\n        # Reject known-inexact VAE modes before any large component download.\n        self.vae_config.resolved_parallel_decode_mode()\n        if current_platform.is_mps():\n            required_components = (\n                \"transformer\",\n                \"text_encoder\",\n                \"video_vae\",\n                \"audio_vae\",\n            )\n            missing_components = [\n                component\n                for component in required_components\n                if server_args.residency_mode(component) != LAYERWISE_OFFLOAD\n            ]\n            if missing_components:\n                raise ValueError(\n                    \"MiniMax-H3 on MPS requires synchronous layerwise offload for \"\n                    f\"{missing_components}; pass --layerwise-offload-components \"\n                    \"transformer text_encoder video_vae audio_vae\"\n                )\n            if server_args.enable_torch_compile:\n                raise ValueError(\n                    \"MiniMax-H3 MPS execution does not support torch.compile; \"\n                    \"pass --enable-torch-compile false\"\n                )\n        selected_backend = self.resolve_transformer_attention_backend(server_args)\n        if (\n            int(server_args.ring_degree or 1) > 1\n            and selected_backend is not AttentionBackendEnum.FA\n        ):\n            raise ValueError(\n                \"MiniMax-H3 ring parallelism requires the FlashAttention \"\n                \"backend for the transformer\"\n            )","sourceCodeStart":224,"sourceCodeEnd":260,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/configs/pipeline_configs/minimax_h3.py#L224-L260","documentation":"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.","triggerScenarios":"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).","commonSituations":"Local development on Apple Silicon Macs; users porting CUDA launch flags directly to MPS; partial offload flags copied from another model's recipe.","solutions":["Launch with --layerwise-offload-components transformer text_encoder video_vae audio_vae","Ensure every one of the four listed components resolves to LAYERWISE_OFFLOAD, not just some (the error names the missing ones)","If full offload is unacceptable, use a CUDA/H200 host instead of MPS"],"exampleFix":"# before\npython -m sglang.launch_server --model MiniMax-H3 --device mps\n\n# after\npython -m sglang.launch_server --model MiniMax-H3 --device mps \\\n  --layerwise-offload-components transformer text_encoder video_vae audio_vae","handlingStrategy":"validation","validationCode":"required = [\"transformer\", \"text_encoder\", \"video_vae\", \"audio_vae\"]\nmissing = [c for c in required if server_args.residency_mode(c) != LAYERWISE_OFFLOAD]\nassert not missing, missing","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use a dedicated MPS launch preset that includes the four offload components","Fail fast in your launcher when device is MPS and offload flags are absent"],"tags":["minimax-h3","mps","apple-silicon","memory-offload","server-args"],"backgroundTag":"missing-required-flag","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}