{"record":{"id":"678167bf0f7b416c","repo":"hiyouga/LlamaFactory","slug":"hyperparallel-trainer-requires-accelerate-fsdp2-mo","errorCode":null,"errorMessage":"HyperParallel trainer requires Accelerate FSDP2 mode to be enabled.","messagePattern":"HyperParallel trainer requires Accelerate FSDP2 mode to be enabled\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/train/hyper_parallel/trainer.py","lineNumber":163,"sourceCode":"        finetuning_args=None,\n        processor=None,\n        ref_model: Optional[nn.Module] = None,\n        **kwargs,\n    ):\n        self._hp_args = hp_args\n\n        # Let CustomSeq2SeqTrainer handle everything except ref_model —\n        # Custom would prepare it with accelerate's fsdp2_prepare_model,\n        # but we need HP's version instead.\n        super().__init__(\n            finetuning_args=finetuning_args,\n            processor=processor,\n            ref_model=None,\n            **kwargs,\n        )\n\n        if not getattr(self.accelerator, \"is_fsdp2\", False):\n            raise ValueError(\"HyperParallel trainer requires Accelerate FSDP2 mode to be enabled.\")\n\n        self._cp_size = hp_args.cp_size\n        self._cp_rank = get_cp_rank(hp_args) if self._cp_size > 1 else 0\n        self._dp_rank = get_dp_rank(hp_args) if self._cp_size > 1 else get_platform().get_rank()\n\n        # Prepare ref_model with the same CP + HSDP path as the train model.\n        self.ref_model = ref_model\n        if self.ref_model is not None:\n            self.ref_model = self._prepare_model_for_hyper_parallel(self.ref_model)\n\n        self._orig_accelerator_clip_grad_norm = self.accelerator.clip_grad_norm_\n        self._orig_fsdp2_prepare_model = None\n        self._accelerator_patches_active = False\n\n    def _prepare_model_for_hyper_parallel(self, model: nn.Module) -> nn.Module:\n        \"\"\"Apply CP runtime hooks before delegating to HyperParallel FSDP2 preparation.\"\"\"\n        if self._cp_size > 1:\n            model = cp_prepare_model(model, self.accelerator, self._hp_args)","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/train/hyper_parallel/trainer.py#L145-L181","documentation":"Error \"HyperParallel trainer requires Accelerate FSDP2 mode to be enabled.\" thrown in hiyouga/LlamaFactory.","triggerScenarios":"Thrown at src/llamafactory/train/hyper_parallel/trainer.py:163 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Enable FSDP2 in the Accelerate config (fsdp_config with fsdp_version: 2) so accelerator.is_fsdp2 is true before running HyperParallel training."],"exampleFix":"# accelerate config\nfsdp_config:\n  fsdp_version: 2","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}