{"record":{"id":"d1feeba88b1ee3ab","repo":"huggingface/transformers","slug":"expert-parallelism-was-requested-enable-expert-p","errorCode":null,"errorMessage":"Expert parallelism was requested (`enable_expert_parallel=True`), but `{self.__class__.__name__}` does not define an expert-parallel plan. Add a `base_model_ep_plan` to its config, or disable expert parallelism.","messagePattern":"Expert parallelism was requested \\(`enable_expert_parallel=True`\\), but `(.+?)` does not define an expert-parallel plan\\. Add a `base_model_ep_plan` to its config, or disable expert parallelism\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/distributed/mixin.py","lineNumber":93,"sourceCode":"            self._ep_plan.update(self.config.base_model_ep_plan or {})\n            self._fsdp_plan.update(self.config.base_model_fsdp_plan or {})\n\n        for name, module in self.named_children():\n            if plan := getattr(module, \"_ep_plan\", None):\n                self._ep_plan.update({f\"{name}.{k}\": v for k, v in plan.copy().items()})\n            if plan := getattr(module, \"_tp_plan\", None):\n                self._tp_plan.update({f\"{name}.{k}\": v for k, v in plan.copy().items()})\n            if plan := getattr(module, \"_pp_plan\", None):\n                self._pp_plan.update({f\"{name}.{k}\": v for k, v in plan.copy().items()})\n            if plan := getattr(module, \"_fsdp_plan\", None):\n                self._fsdp_plan.update({f\"{name}.{k}\": v for k, v in plan.copy().items()})\n\n    @property\n    def tp_plan(self) -> dict[str, str]:\n        \"\"\"The full tp plan for the model's modules.\"\"\"\n        if hasattr(self.config, \"distributed_config\") and self.config.distributed_config.enable_expert_parallel:\n            if not self._ep_plan:\n                raise ValueError(\n                    f\"Expert parallelism was requested (`enable_expert_parallel=True`), but \"\n                    f\"`{self.__class__.__name__}` does not define an expert-parallel plan. Add a \"\n                    f\"`base_model_ep_plan` to its config, or disable expert parallelism.\"\n                )\n            return self._ep_plan\n        return self._tp_plan\n\n    @property\n    def fsdp_plan(self) -> dict[str, str]:\n        return self._fsdp_plan\n\n    @property\n    def pp_plan(self) -> dict[str, tuple[str, str]]:\n        return self._pp_plan\n\n    @tp_plan.setter\n    def tp_plan(self, plan: dict[str, str] | None):\n        if plan is None:","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/distributed/mixin.py#L75-L111","documentation":"The tp_plan property on distributed model mixins switches to the expert-parallel plan when the config sets enable_expert_parallel=True. If the model class never declared an expert-parallel plan (base_model_ep_plan on the config / _ep_plan on the class), the property raises instead of silently falling back to regular TP, because MoE expert sharding requires explicit placement that cannot be inferred.","triggerScenarios":"Loading a MoE model with DistributedConfig(enable_expert_parallel=True) when the model integration lacks base_model_ep_plan; toggling enable_expert_parallel in a config JSON for a model that only defines standard tp plans; accessing model.tp_plan on such a model.","commonSituations":"Enabling expert parallelism on a MoE (e.g. Mixtral/Qwen-MoE family) whose version does not yet ship an EP plan; mixing generic TP configs with MoE-specific features; porting configs between models.","solutions":["Disable expert parallelism: set enable_expert_parallel=False (or omit it) in DistributedConfig and use plain TP.","Keep expert parallelism only on model integrations that declare base_model_ep_plan; upgrade transformers if a newer release added the plan for your model.","For your own MoE integration, declare base_model_ep_plan on the config and _ep_plan on the head class mapping expert modules to expert-parallel sharding."],"exampleFix":"# before\ncfg = DistributedConfig(tp_size=8, enable_expert_parallel=True)  # no EP plan -> raises\n\n# after\ncfg = DistributedConfig(tp_size=8, enable_expert_parallel=False)\n# or use a model version that declares base_model_ep_plan","handlingStrategy":"validation","validationCode":"ep_requested = getattr(model.config, \"distributed_config\", None)\nif ep_requested is not None and ep_requested.enable_expert_parallel and not getattr(model, \"_ep_plan\", None):\n    ep_requested.enable_expert_parallel = False  # or raise, depending on policy","typeGuard":"def supports_expert_parallel(model) -> bool:\n    return bool(getattr(model, \"_ep_plan\", None))","tryCatchPattern":"try:\n    plan = model.tp_plan\nexcept ValueError as e:\n    if \"expert-parallel\" in str(e):\n        model.config.distributed_config.enable_expert_parallel = False\n        plan = model.tp_plan  # plain TP plan now\n    else:\n        raise","preventionTips":["Only enable enable_expert_parallel for models that declare base_model_ep_plan.","Validate the flag against model support in your launcher before training.","Upgrade transformers when MoE EP support is added for your model."],"tags":["distributed","expert-parallelism","moe","tensor-parallelism"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}