Lightning-AI/pytorch-lightning · error · MisconfigurationException

The provided `pruning_fn` {pruning_fn} isn't available in Py

Error message

The provided `pruning_fn` {pruning_fn} isn't available in PyTorch's built-in functions: {list(_PYTORCH_PRUNING_FUNCTIONS.keys())} 

What it means

When pruning_fn is given as a string, ModelPruning resolves it against PyTorch's built-in pruning functions (e.g., 'l1_unstructured', 'random_unstructured', 'ln_structured', 'random_structured', indexed in _PYTORCH_PRUNING_FUNCTIONS). An unknown string (note: it is lowercased before lookup) raises MisconfigurationException listing the valid keys.

Source

Thrown at src/lightning/pytorch/callbacks/pruning.py:183

        self._use_lottery_ticket_hypothesis = use_lottery_ticket_hypothesis
        self._resample_parameters = resample_parameters
        self._prune_on_train_epoch_end = prune_on_train_epoch_end
        self._parameter_names = parameter_names or self.PARAMETER_NAMES
        self._global_kwargs: dict[str, Any] = {}
        self._original_layers: Optional[dict[int, _LayerRef]] = None
        self._pruning_method_name: Optional[str] = None

        for name in self._parameter_names:
            if name not in self.PARAMETER_NAMES:
                raise MisconfigurationException(
                    f"The provided `parameter_names` name: {name} isn't in {self.PARAMETER_NAMES}"
                )

        if isinstance(pruning_fn, str):
            pruning_kwargs = {}
            pruning_fn = pruning_fn.lower()
            if pruning_fn not in _PYTORCH_PRUNING_FUNCTIONS:
                raise MisconfigurationException(
                    f"The provided `pruning_fn` {pruning_fn} isn't available in PyTorch's"
                    f" built-in functions: {list(_PYTORCH_PRUNING_FUNCTIONS.keys())} "
                )
            if pruning_fn.endswith("_structured"):
                if pruning_dim is None:
                    raise MisconfigurationException(
                        "When requesting `structured` pruning, the `pruning_dim` should be provided."
                    )
                if pruning_fn == "ln_structured":
                    if pruning_norm is None:
                        raise MisconfigurationException(
                            "When requesting `ln_structured` pruning, the `pruning_norm` should be provided."
                        )
                    pruning_kwargs["n"] = pruning_norm
                pruning_kwargs["dim"] = pruning_dim
            pruning_fn = self._create_pruning_fn(pruning_fn, **pruning_kwargs)
        elif self._is_pruning_method(pruning_fn):
            if not use_global_unstructured:

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Use a key from the message's list, e.g., pruning_fn='l1_unstructured'
2. Or pass a torch.nn.utils.prune.BasePruningMethod subclass instead of a string
3. Print/inspect _PYTORCH_PRUNING_FUNCTIONS keys for your installed version before writing the config

Example fix

# before
ModelPruning(pruning_fn='l1')
# after
ModelPruning(pruning_fn='l1_unstructured')

fn = cfg['pruning_fn'].lower()
# valid keys: l1_unstructured, random_unstructured, ln_structured, random_structured
assert fn in {'l1_unstructured', 'random_unstructured', 'ln_structured', 'random_structured'}, fn

def is_builtin_pruning_fn(name: str) -> bool:
    return name.lower() in {'l1_unstructured', 'random_unstructured', 'ln_structured', 'random_structured'}

When it happens

Trigger: Passing pruning_fn='l1' or 'L1Unstructured' (case is handled by .lower(), but the key must still match a builtin name like 'l1_unstructured'); passing 'magnitude_pruning' or another non-builtin name.

Common situations: Assuming short names like 'l1' work; configs copied from tutorials using custom callables; version differences in which builtins Lightning maps.

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

• The provided `parameter_names` name: {name} isn't in {self.P
• `pruning_fn` is expected to be a str in {list(_PYTORCH_PRUNI
• `verbose` must be any of (0, 1, 2)
• The provided `parameters_to_prune` should either be list of
• Invalid value for every_n_train_steps={self._every_n_train_s

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