Lightning-AI/pytorch-lightning · error · MisconfigurationException

f"`gradient_clip_algorithm` {gradient_clip_algorithm} is inv

Error message

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

What it means

gradient_clip_algorithm was not one of the supported clipping algorithms. Lightning supports only the values in GradClipAlgorithmType (norm and value); anything else is rejected as a MisconfigurationException.

Source

Thrown at src/lightning/pytorch/trainer/trainer.py:477

            max_time,
        )

        # init data flags
        self.check_val_every_n_epoch: Optional[int]
        self._data_connector.on_trainer_init(
            val_check_interval,
            reload_dataloaders_every_n_epochs,
            check_val_every_n_epoch,
        )

        # gradient clipping
        if gradient_clip_val is not None and 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 gradient_clip_algorithm is not None and 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()}."
            )

        self.gradient_clip_val: Optional[Union[int, float]] = gradient_clip_val
        self.gradient_clip_algorithm: Optional[GradClipAlgorithmType] = (
            GradClipAlgorithmType(gradient_clip_algorithm.lower()) if gradient_clip_algorithm is not None else None
        )

        if detect_anomaly:
            rank_zero_info(
                "You have turned on `Trainer(detect_anomaly=True)`. This will significantly slow down compute speed and"
                " is recommended only for model debugging."
            )
        self._detect_anomaly: bool = detect_anomaly

        setup._log_device_info(self)

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Use gradient_clip_algorithm="norm" (default) or "value"
2. Check the error message which lists GradClipAlgorithmType.supported_types()
3. Fix the typo in the string

Example fix

# before
trainer = Trainer(gradient_clip_algorithm="gradd_norm")
# after
trainer = Trainer(gradient_clip_algorithm="norm")

from lightning.pytorch.trainer import GradClipAlgorithmType  # or lightning_fabric.utilities
algo = cfg.get("gradient_clip_algorithm")
if algo is not None and algo.lower() not in ("norm", "value"):
    raise ValueError(f"unsupported clip algo {algo}")

def is_valid_clip_algo(a) -> bool:
    return a is None or str(a).lower() in {"norm", "value"}

When it happens

Trigger: Trainer(gradient_clip_algorithm="gradd") (typo), "global_norm", or another framework's algorithm name; the check is case-insensitive against the allowed set.

Common situations: Typos, porting code from other frameworks expecting different algorithm names, or assuming more clipping modes exist than are implemented.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• You requested to find {num_devices} devices but this machine
• `gradient_clip_algorithm` {gradient_clip_algorithm} is inval
• You selected an invalid strategy name: `strategy={strategy!r
• You selected an invalid accelerator name: `accelerator={acce
• f"`Trainer(barebones=True, log_every_n_steps={log_every_n_st

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