{"record":{"id":"b8dbddf9f905338a","repo":"Lightning-AI/pytorch-lightning","slug":"gradient-clip-algorithm-gradient-clip-algorithm","errorCode":null,"errorMessage":"`gradient_clip_algorithm` {gradient_clip_algorithm} is invalid. Allowed algorithms: {GradClipAlgorithmType.supported_types()}.","messagePattern":"`gradient_clip_algorithm` (.+?) is invalid\\. Allowed algorithms: (.+?)\\.","errorType":"exception","errorClass":"MisconfigurationException","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/core/module.py","lineNumber":1287,"sourceCode":"        if gradient_clip_algorithm is None:\n            gradient_clip_algorithm = self.trainer.gradient_clip_algorithm or \"norm\"\n        else:\n            gradient_clip_algorithm = gradient_clip_algorithm.lower()\n            if (\n                self.trainer.gradient_clip_algorithm is not None\n                and self.trainer.gradient_clip_algorithm != gradient_clip_algorithm\n            ):\n                raise MisconfigurationException(\n                    f\"You have set `Trainer(gradient_clip_algorithm={self.trainer.gradient_clip_algorithm.value!r})`\"\n                    f\" and have passed `clip_gradients(gradient_clip_algorithm={gradient_clip_algorithm!r})\"\n                    \" Please use only one of them.\"\n                )\n\n        if not isinstance(gradient_clip_val, (int, float)):\n            raise TypeError(f\"`gradient_clip_val` should be an int or a float. Got {gradient_clip_val}.\")\n\n        if not GradClipAlgorithmType.supported_type(gradient_clip_algorithm.lower()):\n            raise MisconfigurationException(\n                f\"`gradient_clip_algorithm` {gradient_clip_algorithm} is invalid.\"\n                f\" Allowed algorithms: {GradClipAlgorithmType.supported_types()}.\"\n            )\n\n        gradient_clip_algorithm = GradClipAlgorithmType(gradient_clip_algorithm)\n        self.trainer.precision_plugin.clip_gradients(optimizer, gradient_clip_val, gradient_clip_algorithm)\n\n    def configure_gradient_clipping(\n        self,\n        optimizer: Optimizer,\n        gradient_clip_val: Optional[Union[int, float]] = None,\n        gradient_clip_algorithm: Optional[str] = None,\n    ) -> None:\n        \"\"\"Perform gradient clipping for the optimizer parameters. Called before :meth:`optimizer_step`.\n\n        Args:\n            optimizer: Current optimizer being used.\n            gradient_clip_val: The value at which to clip gradients. By default, value passed in Trainer","sourceCodeStart":1269,"sourceCodeEnd":1305,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/core/module.py#L1269-L1305","documentation":"clip_gradients checks the algorithm string against GradClipAlgorithmType.supported_type(); only known algorithms (e.g. 'norm', 'value') are accepted. Any other string (typos, unsupported methods like 'adaptive') raises MisconfigurationException listing the allowed options.","triggerScenarios":"self.clip_gradients(optimizer, gradient_clip_algorithm='norms') (typo) or Trainer(gradient_clip_algorithm='adafactor').","commonSituations":"Typos in config YAML; assumptions that newer PyTorch clipping algorithms are supported; copied algorithm names from other frameworks.","solutions":["Use one of the allowed algorithms from GradClipAlgorithmType (currently 'norm' or 'value')","Fix typos in the config key","For unsupported clipping schemes, implement custom clipping in configure_gradient_clipping"],"exampleFix":"# before\nself.clip_gradients(optimizer, gradient_clip_val=1.0, gradient_clip_algorithm='norms')\n\n# after\nfrom lightning.pytorch.utilities import GradClipAlgorithmType\nself.clip_gradients(optimizer, gradient_clip_val=1.0, gradient_clip_algorithm='norm')","handlingStrategy":"validation","validationCode":"from lightning.pytorch.utilities import GradClipAlgorithmType\nalgo = algo.lower()\nif not GradClipAlgorithmType.supported_type(algo):\n    raise ValueError(f'unsupported clip algorithm {algo}; allowed: {GradClipAlgorithmType.supported_types()}')","typeGuard":"def is_supported_clip_algorithm(name: str) -> bool:\n    from lightning.pytorch.utilities import GradClipAlgorithmType\n    return GradClipAlgorithmType.supported_type(name.lower())","tryCatchPattern":null,"preventionTips":["Validate algorithm strings against GradClipAlgorithmType at config parse time","Restrict config schema to enum values ['norm','value']"],"tags":["pytorch-lightning","gradient-clipping","invalid-argument","enum-validation"],"backgroundTag":"gradient-clipping-misconfigured","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}