Lightning-AI/pytorch-lightning · error · MisconfigurationException

You have set `Trainer(gradient_clip_algorithm={self.trainer.

Error message

You have set `Trainer(gradient_clip_algorithm={self.trainer.gradient_clip_algorithm.value!r})` and have passed `clip_gradients(gradient_clip_algorithm={gradient_clip_algorithm!r}) Please use only one of them.

What it means

clip_gradients raises when both Trainer(gradient_clip_algorithm=...) and a different gradient_clip_algorithm argument to self.clip_gradients are supplied. Lightning forbids two conflicting algorithm selections (e.g. 'norm' in Trainer vs 'value' in the call).

Source

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

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

        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(

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Set the algorithm in one place only — preferably Trainer(gradient_clip_algorithm=...)
2. Call self.clip_gradients(optimizer) without algorithm args so the Trainer's setting applies
3. Align both values if you keep them in both places

Example fix

# before
trainer = L.Trainer(gradient_clip_algorithm='norm')
self.clip_gradients(optimizer, gradient_clip_algorithm='value')

# after
trainer = L.Trainer(gradient_clip_algorithm='norm')
self.clip_gradients(optimizer, gradient_clip_val=1.0)  # algorithm inherited

if trainer.gradient_clip_algorithm is not None:
    self.clip_gradients(optimizer, gradient_clip_val=v)  # algorithm from Trainer
else:
    self.clip_gradients(optimizer, gradient_clip_val=v, gradient_clip_algorithm='norm')

def algorithm_conflict(trainer, algo) -> bool:
    return trainer.gradient_clip_algorithm is not None and algo is not None and trainer.gradient_clip_algorithm != algo

When it happens

Trigger: Trainer(gradient_clip_algorithm='norm') plus self.clip_gradients(optimizer, gradient_clip_algorithm='value') inside configure_gradient_clipping.

Common situations: Template code passes the algorithm explicitly while the Trainer already configures it; migration from scripts that set clipping only in the module.

Related errors

• You have set `Trainer(gradient_clip_val={self.trainer.gradie
• Gradient clipping is not implemented for optimizers handling
• `gradient_clip_val` should be an int or a float. Got {gradie
• `gradient_clip_algorithm` {gradient_clip_algorithm} is inval
• The current optimizer, {type(optimizer).__qualname__}, does

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