Lightning-AI/pytorch-lightning · error · ValueError

You have to specify either `clip_val` or `max_norm` to do gr

Error message

You have to specify either `clip_val` or `max_norm` to do gradient clipping!

What it means

Fabric.clip_gradients() is a no-op without a clipping specification. If both `clip_val` and `max_norm` are None the function falls through to raise ValueError, forcing the caller to state which clipping algorithm to apply.

Source

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

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

        Use this only if the `forward` method of your model does not cover all operations you wish to run with the
        chosen precision setting.

        """
        return self._precision.forward_context()

    @overload
    def to_device(self, obj: nn.Module) -> nn.Module: ...

    @overload
    def to_device(self, obj: Tensor) -> Tensor: ...

    @overload
    def to_device(self, obj: Any) -> Any: ...

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Pass clip_val=<float> or max_norm=<float> explicitly
2. If clipping should be conditional, guard the call: only invoke clip_gradients when configured
3. Fix config parsing so None defaults become a real value

Example fix

# before
fabric.clip_gradients(model, optimizer, clip_val=cfg.clip_val)  # cfg.clip_val is None
# after
if cfg.clip_val is not None:
    fabric.clip_gradients(model, optimizer, clip_val=cfg.clip_val)

if clip_val is not None:
    fabric.clip_gradients(model, optimizer, clip_val=clip_val)
elif max_norm is not None:
    fabric.clip_gradients(model, optimizer, max_norm=max_norm)
# else: no clipping intended — skip the call

When it happens

Trigger: Calling fabric.clip_gradients(model, optimizer) with neither clip_val nor max_norm, e.g. because a hyperparameter defaulted to None (from a config file or CLI arg) and was forwarded verbatim.

Common situations: Config-driven training where clipping values are optional; refactoring a method that used to skip clipping silently when unset.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Only one of `clip_val` or `max_norm` can be set as this spec
• 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/853c44c939da59c0. Report an issue: GitHub.