{"record":{"id":"5daee8a33f6d3ecd","repo":"Lightning-AI/pytorch-lightning","slug":"only-one-of-clip-val-or-max-norm-can-be-set-as","errorCode":null,"errorMessage":"Only one of `clip_val` or `max_norm` can be set as this specifies the underlying clipping algorithm!","messagePattern":"Only one of `clip_val` or `max_norm` can be set as this specifies the underlying clipping algorithm!","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/fabric.py","lineNumber":566,"sourceCode":"\n        Returns:\n            The total norm of the gradients (before clipping was applied) as a scalar tensor if ``max_norm`` was\n            passed, otherwise ``None``.\n\n        Raises:\n            ValueError: If both ``clip_val`` and ``max_norm`` are provided, or if neither is provided.\n\n        Example::\n\n            # Clip by value\n            fabric.clip_gradients(model, optimizer, clip_val=1.0)\n\n            # Clip by norm\n            total_norm = fabric.clip_gradients(model, optimizer, max_norm=1.0)\n\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.","sourceCodeStart":548,"sourceCodeEnd":584,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/fabric.py#L548-L584","documentation":"Fabric.clip_gradients() supports two mutually exclusive clipping algorithms: value clipping (`clip_val`) and norm clipping (`max_norm`, optionally with norm_type/error_if_nonfinite). Specifying both at once is contradictory because each selects a different underlying strategy method (clip_gradients_value vs clip_gradients_norm), so Fabric raises ValueError.","triggerScenarios":"Calling fabric.clip_gradients(model, optimizer, clip_val=0.5, max_norm=1.0) — both keyword arguments non-None. Often happens when merging example code that used clip_val with code that used max_norm.","commonSituations":"Copy-pasting gradient-clipping snippets from different tutorials; incrementally adding max_norm to existing clip_val code; switching algorithms without deleting the old kwarg.","solutions":["Pick one: keep clip_val=0.8 for value clipping OR max_norm=1.0 for norm clipping and delete the other kwarg","Prefer max_norm (norm clipping) unless you specifically need value clipping"],"exampleFix":"# before\nfabric.clip_gradients(model, optimizer, clip_val=0.5, max_norm=1.0)\n# after\nfabric.clip_gradients(model, optimizer, max_norm=1.0)","handlingStrategy":"type-guard","validationCode":"assert not (clip_val is not None and max_norm is not None), 'pass only one of clip_val/max_norm'","typeGuard":"def clip_kwargs_ok(clip_val, max_norm):\n    return (clip_val is None) != (max_norm is None)","tryCatchPattern":null,"preventionTips":["Make clipping mode a single config enum (e.g. clip_mode: 'val'|'norm') instead of two optional fields"],"tags":["lightning","fabric","gradient-clipping","mutually-exclusive-args"],"backgroundTag":"conflicting-arguments","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}