Lightning-AI/pytorch-lightning · error · MisconfigurationException

`pruning_fn` is expected to be a str in {list(_PYTORCH_PRUNI

Error message

`pruning_fn` is expected to be a str in {list(_PYTORCH_PRUNING_FUNCTIONS.keys())} or a PyTorch `BasePruningMethod`. Found: {pruning_fn}. HINT: if passing a `BasePruningMethod`, pass the class, not an instance

What it means

pruning_fn must be either a string naming a PyTorch built-in pruning function or a torch BasePruningMethod subclass. Anything else (an instance of a method, an int, None, an arbitrary callable) hits the final else branch in __init__ and raises MisconfigurationException, with a hint that the class (not an instance) must be passed.

Source

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

                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:
                raise MisconfigurationException(
                    "PyTorch `BasePruningMethod` is currently only supported with `use_global_unstructured=True`."
                )
        else:
            raise MisconfigurationException(
                f"`pruning_fn` is expected to be a str in {list(_PYTORCH_PRUNING_FUNCTIONS.keys())}"
                f" or a PyTorch `BasePruningMethod`. Found: {pruning_fn}."
                " HINT: if passing a `BasePruningMethod`, pass the class, not an instance"
            )

        # need to ignore typing here since pytorch base class does not define the PRUNING_TYPE attribute
        if use_global_unstructured and pruning_fn.PRUNING_TYPE != "unstructured":  # type: ignore
            raise MisconfigurationException(
                'Only the "unstructured" PRUNING_TYPE is supported with `use_global_unstructured=True`.'
                f" Found method {pruning_fn} of type {pruning_fn.PRUNING_TYPE}. "  # type: ignore[union-attr]
            )

        self.pruning_fn = pruning_fn
        self._apply_pruning = apply_pruning
        self._make_pruning_permanent = make_pruning_permanent

        if not (isinstance(amount, (int, float)) or callable(amount)):
            raise MisconfigurationException(

View on GitHub (pinned to 9fed5c27d2)

Solutions

Pass the class, not an instance: pruning_fn=torch.nn.utils.prune.L1Unstructured
Or pass a valid string like 'l1_unstructured'
Wrap genuinely custom logic in a BasePruningMethod subclass (with PRUNING_TYPE set) and pass that class

Example fix

# before
import torch.nn.utils.prune as prune
ModelPruning(pruning_fn=prune.L1Unstructured())
# after
ModelPruning(pruning_fn=prune.L1Unstructured)  # or pruning_fn='l1_unstructured'

Defensive patterns

Strategy: type-guard

Validate before calling

import torch.nn.utils.prune as prune
assert isinstance(pruning_fn, str) or (isinstance(pruning_fn, type) and issubclass(pruning_fn, prune.BasePruningMethod)), 'pass a string name or the method CLASS'

Type guard

def is_valid_pruning_fn(fn) -> bool:
    import torch.nn.utils.prune as prune
    return isinstance(fn, str) or (isinstance(fn, type) and issubclass(fn, prune.BasePruningMethod))

Prevention

Never pass an instance of a pruning method; pass the class or a string name
Subclass BasePruningMethod for custom logic

When it happens

Trigger: ModelPruning(pruning_fn=prune.l1_unstructured(model...)) — passing the result (tensor/mask) instead of the function; passing prune.L1Unstructured() (an instance) instead of prune.L1Unstructured (the class); passing a plain lambda.

Common situations: Confusing the callback API with torch.nn.utils.prune's functional API; instantiating method classes out of habit; passing functools.partial objects.

Understand the failure class

Background: "Wrong argument type", "must be a string", "expected Array or Prism::Scope": TypeError and ArgumentError when a library receives a value of the wrong type — this error's family across 28 libraries.

Related errors

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