Lightning-AI/pytorch-lightning · error · MisconfigurationException

You have set `Trainer(gradient_clip_val={self.trainer.gradie

Error message

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

What it means

LightningModule.clip_gradients rejects specifying gradient clipping twice: once via Trainer(gradient_clip_val=...) and again via self.clip_gradients(gradient_clip_val=...) with a different value. Only one source of the clipping value is allowed.

Source

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

            gradient_clip_val: The value at which to clip gradients.
            gradient_clip_algorithm: The gradient clipping algorithm to use. Pass ``gradient_clip_algorithm="value"``
                to clip by value, and ``gradient_clip_algorithm="norm"`` to clip by norm.

        """

        if self.fabric is not None:
            self.fabric.clip_gradients(
                self,
                optimizer,
                clip_val=gradient_clip_val if gradient_clip_algorithm == GradClipAlgorithmType.VALUE else None,
                max_norm=None if gradient_clip_algorithm == GradClipAlgorithmType.VALUE else gradient_clip_val,
            )
            return

        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."
                )

View on GitHub (pinned to 9fed5c27d2)

Solutions

Remove gradient_clip_val from the Trainer and control clipping solely via self.clip_gradients
Or keep the Trainer value and call self.clip_gradients(optimizer) without gradient_clip_val so the Trainer's value is used
Make the values identical if both paths must remain (then no error is raised)

Example fix

# before
trainer = L.Trainer(gradient_clip_val=1.0)
# in module:
def configure_gradient_clipping(self, optimizer, gradient_clip_val=None):
    self.clip_gradients(optimizer, gradient_clip_val=0.5)  # conflict

# after
trainer = L.Trainer()  # no gradient_clip_val
def configure_gradient_clipping(self, optimizer, gradient_clip_val=None):
    self.clip_gradients(optimizer, gradient_clip_val=0.5)

Defensive patterns

Strategy: validation

Validate before calling

if trainer.gradient_clip_val is not None:
    self.clip_gradients(optimizer)  # inherit Trainer's value
else:
    self.clip_gradients(optimizer, gradient_clip_val=clip_val)

Type guard

def clip_val_conflict(trainer, clip_val) -> bool:
    return trainer.gradient_clip_val is not None and clip_val is not None and trainer.gradient_clip_val != clip_val

Try / catch

from lightning.pytorch.utilities.exceptions import MisconfigurationException
try:
    self.clip_gradients(optimizer, gradient_clip_val=v)
except MisconfigurationException:
    self.clip_gradients(optimizer)  # fall back to Trainer-configured value

Prevention

Configure clipping in exactly one place: Trainer args OR module code
Add a startup assert that Trainer clipping args and module clipping args don't both exist

When it happens

Trigger: Trainer instantiated with gradient_clip_val=1.0 and later calling self.clip_gradients(optimizer, gradient_clip_val=0.5) inside training_step (typically when overriding configure_gradient_clipping).

Common situations: User copied manual clipping code into a Trainer that already sets gradient_clip_val; changed clipping schedule per step without removing the Trainer arg.

Related errors

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