{"record":{"id":"556279dcc753827e","repo":"Lightning-AI/pytorch-lightning","slug":"gradient-clipping-with-fsdp-is-only-possible-if-th","errorCode":null,"errorMessage":"Gradient clipping with FSDP is only possible if the module passed to `{type(self).__name__}.clip_gradients_norm` is wrapped in `FullyShardedDataParallel`. Got: {module.__class__.__name__}.","messagePattern":"Gradient clipping with FSDP is only possible if the module passed to `(.+?)\\.clip_gradients_norm` is wrapped in `FullyShardedDataParallel`\\. Got: (.+?)\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/strategies/fsdp.py","lineNumber":416,"sourceCode":"        obj = [obj]\n        torch.distributed.broadcast_object_list(obj, src, group=_group.WORLD)\n        return obj[0]\n\n    @override\n    def clip_gradients_norm(\n        self,\n        module: Module,\n        optimizer: Optimizer,\n        max_norm: Union[float, int],\n        norm_type: Union[float, int] = 2.0,\n        error_if_nonfinite: bool = True,\n    ) -> Tensor:\n        \"\"\"Clip gradients by norm.\"\"\"\n        from torch.distributed.fsdp.fully_sharded_data_parallel import FullyShardedDataParallel\n\n        if not isinstance(module, FullyShardedDataParallel):\n            # the root must be wrapped\n            raise TypeError(\n                \"Gradient clipping with FSDP is only possible if the module passed to\"\n                f\" `{type(self).__name__}.clip_gradients_norm` is wrapped in `FullyShardedDataParallel`.\"\n                f\" Got: {module.__class__.__name__}.\"\n            )\n        self.precision.unscale_gradients(optimizer)\n        return module.clip_grad_norm_(max_norm=max_norm, norm_type=norm_type)\n\n    @override\n    def save_checkpoint(\n        self,\n        path: _PATH,\n        state: dict[str, Union[Module, Optimizer, Any]],\n        storage_options: Optional[Any] = None,\n        filter: Optional[dict[str, Callable[[str, Any], bool]]] = None,\n    ) -> None:\n        \"\"\"Save model, optimizer, and other state to a checkpoint on disk.\n\n        If the state-dict-type is ``'full'``, the checkpoint will be written to a single file containing the weights,","sourceCodeStart":398,"sourceCodeEnd":434,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/strategies/fsdp.py#L398-L434","documentation":"FSDP gradient clipping by norm must run through FullyShardedDataParallel.clip_grad_norm_ (it needs the sharded/unsharded coordination across ranks). If the module passed to clip_gradients_norm is not an FSDP-wrapped module (typically the unwrapped root), TypeError is raised.","triggerScenarios":"strategy.clip_gradients_norm(module, optimizer, ...) where module is the original unwrapped model (e.g. before setup_module/setup) or a plain nn.Module.","commonSituations":"Calling fabric.clip_gradients on the raw model reference before setup; storing the pre-wrap model and clipping after; partially refactored custom loops.","solutions":["Use the wrapped module returned by fabric.setup/setup_module for clipping","Ensure clipping happens after setup, and you keep the returned (wrapped) reference","Clip manually with the FSDP API on the wrapped root if you need custom behavior"],"exampleFix":"# before\nraw_model = MyModel()\noptimizer = ...\nstrategy.clip_gradients_norm(raw_model, optimizer, max_norm=1.0)\n\n# after\nmodel, optimizer = fabric.setup(raw_model, optimizer)\nstrategy.clip_gradients_norm(model, optimizer, max_norm=1.0)","handlingStrategy":"type-guard","validationCode":"from torch.distributed.fsdp import FullyShardedDataParallel\nassert isinstance(module, FullyShardedDataParallel), \"clip after fabric.setup, on the wrapped module\"","typeGuard":"from torch.distributed.fsdp import FullyShardedDataParallel\ndef is_fsdp_wrapped(module) -> bool:\n    return isinstance(module, FullyShardedDataParallel)","tryCatchPattern":null,"preventionTips":["Always keep and use the object returned by fabric.setup","Clip only after setup completes"],"tags":["fsdp","gradient-clipping","type-error","wrapping"],"backgroundTag":"module-not-wrapped","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}