{"record":{"id":"853c44c939da59c0","repo":"Lightning-AI/pytorch-lightning","slug":"you-have-to-specify-either-clip-val-or-max-norm","errorCode":null,"errorMessage":"You have to specify either `clip_val` or `max_norm` to do gradient clipping!","messagePattern":"You have to specify either `clip_val` or `max_norm` to do gradient clipping!","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/fabric.py","lineNumber":581,"sourceCode":"\n        \"\"\"\n        if clip_val is not None and max_norm is not None:\n            raise ValueError(\n                \"Only one of `clip_val` or `max_norm` can be set as this specifies the underlying clipping algorithm!\"\n            )\n\n        if clip_val is not None:\n            self.strategy.clip_gradients_value(_unwrap_objects(module), _unwrap_objects(optimizer), clip_val=clip_val)\n            return None\n        if max_norm is not None:\n            return self.strategy.clip_gradients_norm(\n                _unwrap_objects(module),\n                _unwrap_objects(optimizer),\n                max_norm=max_norm,\n                norm_type=norm_type,\n                error_if_nonfinite=error_if_nonfinite,\n            )\n        raise ValueError(\"You have to specify either `clip_val` or `max_norm` to do gradient clipping!\")\n\n    def autocast(self) -> AbstractContextManager:\n        \"\"\"A context manager to automatically convert operations for the chosen precision.\n\n        Use this only if the `forward` method of your model does not cover all operations you wish to run with the\n        chosen precision setting.\n\n        \"\"\"\n        return self._precision.forward_context()\n\n    @overload\n    def to_device(self, obj: nn.Module) -> nn.Module: ...\n\n    @overload\n    def to_device(self, obj: Tensor) -> Tensor: ...\n\n    @overload\n    def to_device(self, obj: Any) -> Any: ...","sourceCodeStart":563,"sourceCodeEnd":599,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/fabric.py#L563-L599","documentation":"Fabric.clip_gradients() is a no-op without a clipping specification. If both `clip_val` and `max_norm` are None the function falls through to raise ValueError, forcing the caller to state which clipping algorithm to apply.","triggerScenarios":"Calling fabric.clip_gradients(model, optimizer) with neither clip_val nor max_norm, e.g. because a hyperparameter defaulted to None (from a config file or CLI arg) and was forwarded verbatim.","commonSituations":"Config-driven training where clipping values are optional; refactoring a method that used to skip clipping silently when unset.","solutions":["Pass clip_val=<float> or max_norm=<float> explicitly","If clipping should be conditional, guard the call: only invoke clip_gradients when configured","Fix config parsing so None defaults become a real value"],"exampleFix":"# before\nfabric.clip_gradients(model, optimizer, clip_val=cfg.clip_val)  # cfg.clip_val is None\n# after\nif cfg.clip_val is not None:\n    fabric.clip_gradients(model, optimizer, clip_val=cfg.clip_val)","handlingStrategy":"validation","validationCode":"if clip_val is not None:\n    fabric.clip_gradients(model, optimizer, clip_val=clip_val)\nelif max_norm is not None:\n    fabric.clip_gradients(model, optimizer, max_norm=max_norm)\n# else: no clipping intended — skip the call","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat clip_gradients as a call you only make when clipping is configured","Give config defaults real values (e.g. max_norm=1.0) rather than None"],"tags":["lightning","fabric","gradient-clipping","missing-argument"],"backgroundTag":"missing-required-parameter","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}