Lightning-AI/pytorch-lightning · error · MisconfigurationException

`gradient_clip_algorithm` {gradient_clip_algorithm} is inval

Error message

`gradient_clip_algorithm` {gradient_clip_algorithm} is invalid. Allowed algorithms: {GradClipAlgorithmType.supported_types()}.

What it means

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.

Source

Thrown at src/lightning/pytorch/core/module.py:1287

        if gradient_clip_algorithm is None:
            gradient_clip_algorithm = self.trainer.gradient_clip_algorithm or "norm"
        else:
            gradient_clip_algorithm = gradient_clip_algorithm.lower()
            if (
                self.trainer.gradient_clip_algorithm is not None
                and self.trainer.gradient_clip_algorithm != gradient_clip_algorithm
            ):
                raise MisconfigurationException(
                    f"You have set `Trainer(gradient_clip_algorithm={self.trainer.gradient_clip_algorithm.value!r})`"
                    f" and have passed `clip_gradients(gradient_clip_algorithm={gradient_clip_algorithm!r})"
                    " Please use only one of them."
                )

        if not isinstance(gradient_clip_val, (int, float)):
            raise TypeError(f"`gradient_clip_val` should be an int or a float. Got {gradient_clip_val}.")

        if not GradClipAlgorithmType.supported_type(gradient_clip_algorithm.lower()):
            raise MisconfigurationException(
                f"`gradient_clip_algorithm` {gradient_clip_algorithm} is invalid."
                f" Allowed algorithms: {GradClipAlgorithmType.supported_types()}."
            )

        gradient_clip_algorithm = GradClipAlgorithmType(gradient_clip_algorithm)
        self.trainer.precision_plugin.clip_gradients(optimizer, gradient_clip_val, gradient_clip_algorithm)

    def configure_gradient_clipping(
        self,
        optimizer: Optimizer,
        gradient_clip_val: Optional[Union[int, float]] = None,
        gradient_clip_algorithm: Optional[str] = None,
    ) -> None:
        """Perform gradient clipping for the optimizer parameters. Called before :meth:`optimizer_step`.

        Args:
            optimizer: Current optimizer being used.
            gradient_clip_val: The value at which to clip gradients. By default, value passed in Trainer

View on GitHub (pinned to 9fed5c27d2)

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

Example fix

# before
self.clip_gradients(optimizer, gradient_clip_val=1.0, gradient_clip_algorithm='norms')

# after
from lightning.pytorch.utilities import GradClipAlgorithmType
self.clip_gradients(optimizer, gradient_clip_val=1.0, gradient_clip_algorithm='norm')

Defensive patterns

Strategy: validation

Validate before calling

from lightning.pytorch.utilities import GradClipAlgorithmType
algo = algo.lower()
if not GradClipAlgorithmType.supported_type(algo):
    raise ValueError(f'unsupported clip algorithm {algo}; allowed: {GradClipAlgorithmType.supported_types()}')

Type guard

def is_supported_clip_algorithm(name: str) -> bool:
    from lightning.pytorch.utilities import GradClipAlgorithmType
    return GradClipAlgorithmType.supported_type(name.lower())

Prevention

Validate algorithm strings against GradClipAlgorithmType at config parse time
Restrict config schema to enum values ['norm','value']

When it happens

Trigger: self.clip_gradients(optimizer, gradient_clip_algorithm='norms') (typo) or Trainer(gradient_clip_algorithm='adafactor').

Common situations: Typos in config YAML; assumptions that newer PyTorch clipping algorithms are supported; copied algorithm names from other frameworks.

Related errors

AI-assisted analysis of Lightning-AI/pytorch-lightning@9fed5c27d2 (2026-08-28). Data as JSON: /api/errors/b8dbddf9f905338a. Report an issue: GitHub.