Lightning-AI/pytorch-lightning · error · MisconfigurationException

Only the "unstructured" PRUNING_TYPE is supported with `use_

Error message

Only the "unstructured" PRUNING_TYPE is supported with `use_global_unstructured=True`. Found method {pruning_fn} of type {pruning_fn.PRUNING_TYPE}.

What it means

ModelPruning applies global unstructured pruning via torch.nn.utils.prune.global_unstructured, which only accepts methods whose PRUNING_TYPE is 'unstructured'. If the resolved pruning_fn (builtin or custom class) has a different PRUNING_TYPE (e.g., 'structured'), __init__ raises MisconfigurationException naming the method and its type.

Source

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

                        )
                    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(
                "`amount` should be provided and be either an int, a float or Callable function."
            )

        self.amount = amount

        if verbose not in (0, 1, 2):
            raise MisconfigurationException("`verbose` must be any of (0, 1, 2)")

View on GitHub (pinned to 9fed5c27d2)

Solutions

  1. Use an unstructured method such as pruning_fn='l1_unstructured' or 'random_unstructured' with global unstructured pruning
  2. For structured pruning needs, pass use_global_unstructured=False with a supported setup, or apply torch structured pruning manually outside this callback
  3. If writing a custom method, ensure PRUNING_TYPE = 'unstructured' in the class definition

Example fix

# before
ModelPruning(pruning_fn='ln_structured', pruning_dim=0, pruning_norm=1)  # default use_global_unstructured=True
# after
ModelPruning(pruning_fn='l1_unstructured', amount=0.5)
Defensive patterns

Strategy: validation

Validate before calling

if use_global_unstructured:
    ptype = getattr(pruning_fn, 'PRUNING_TYPE', 'unstructured')
    assert ptype == 'unstructured', f'global unstructured requires unstructured methods, got {ptype}'

Type guard

def is_unstructured_method(fn) -> bool:
    return getattr(fn, 'PRUNING_TYPE', None) == 'unstructured'

Prevention

When it happens

Trigger: Passing pruning_fn='ln_structured' (a structured method) while leaving use_global_unstructured=True (default); passing a custom BasePruningMethod subclass whose PRUNING_TYPE = 'structured'.

Common situations: Choosing a structured method for channel pruning without realizing the callback routes everything through global_unstructured by default; custom methods copied from PyTorch docs that declare structured types.

Related errors

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