Lightning-AI/pytorch-lightning · error · ValueError

Only one of `clip_val` or `max_norm` can be set as this spec

Error message

Only one of `clip_val` or `max_norm` can be set as this specifies the underlying clipping algorithm!

What it means

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.

Source

Thrown at src/lightning/fabric/fabric.py:566

        Returns:
            The total norm of the gradients (before clipping was applied) as a scalar tensor if ``max_norm`` was
            passed, otherwise ``None``.

        Raises:
            ValueError: If both ``clip_val`` and ``max_norm`` are provided, or if neither is provided.

        Example::

            # Clip by value
            fabric.clip_gradients(model, optimizer, clip_val=1.0)

            # Clip by norm
            total_norm = fabric.clip_gradients(model, optimizer, max_norm=1.0)

        """
        if clip_val is not None and max_norm is not None:
            raise ValueError(
                "Only one of `clip_val` or `max_norm` can be set as this specifies the underlying clipping algorithm!"
            )

        if clip_val is not None:
            self.strategy.clip_gradients_value(_unwrap_objects(module), _unwrap_objects(optimizer), clip_val=clip_val)
            return None
        if max_norm is not None:
            return self.strategy.clip_gradients_norm(
                _unwrap_objects(module),
                _unwrap_objects(optimizer),
                max_norm=max_norm,
                norm_type=norm_type,
                error_if_nonfinite=error_if_nonfinite,
            )
        raise ValueError("You have to specify either `clip_val` or `max_norm` to do gradient clipping!")

    def autocast(self) -> AbstractContextManager:
        """A context manager to automatically convert operations for the chosen precision.

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Pick one: keep clip_val=0.8 for value clipping OR max_norm=1.0 for norm clipping and delete the other kwarg
2. Prefer max_norm (norm clipping) unless you specifically need value clipping

Example fix

# before
fabric.clip_gradients(model, optimizer, clip_val=0.5, max_norm=1.0)
# after
fabric.clip_gradients(model, optimizer, max_norm=1.0)

assert not (clip_val is not None and max_norm is not None), 'pass only one of clip_val/max_norm'

def clip_kwargs_ok(clip_val, max_norm):
    return (clip_val is None) != (max_norm is None)

When it happens

Trigger: 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.

Common situations: Copy-pasting gradient-clipping snippets from different tutorials; incrementally adding max_norm to existing clip_val code; switching algorithms without deleting the old kwarg.

Related errors

• You have to specify either `clip_val` or `max_norm` to do gr
• Received multiple values for {', '.join(duplicated_plugin_ke
• Received both `precision={precision_input}` and `plugins={se
• accelerator set through both strategy class and accelerator
• precision set through both strategy class and plugins, choos

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