Lightning-AI/pytorch-lightning · error · MisconfigurationException

When requesting `structured` pruning, the `pruning_dim` shou

Error message

When requesting `structured` pruning, the `pruning_dim` should be provided.

What it means

Structured pruning methods (names ending in '_structured') need a dimension along which to remove entire channels/neurons. If pruning_fn is a structured method but pruning_dim is None, ModelPruning's __init__ raises MisconfigurationException demanding the dimension.

Source

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

        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:
                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())}"

View on GitHub (pinned to 9fed5c27d2)

Solutions

  1. Add pruning_dim, e.g., pruning_fn='ln_structured', pruning_dim=0
  2. For 'ln_structured' also supply pruning_norm (the n parameter)
  3. Verify dim matches the tensor layout of the modules being pruned (dim=0 prunes output channels for Linear/Conv)

Example fix

# before
ModelPruning(pruning_fn='ln_structured', pruning_norm=2)
# after
ModelPruning(pruning_fn='ln_structured', pruning_norm=2, pruning_dim=0)
Defensive patterns

Strategy: validation

Validate before calling

if str(pruning_fn).endswith('_structured'):
    assert pruning_dim is not None, 'structured pruning requires pruning_dim'

Prevention

When it happens

Trigger: ModelPruning(pruning_fn='ln_structured') or 'random_structured' without pruning_dim; specifying pruning_norm but forgetting dim, or vice versa.

Common situations: Switching from unstructured to structured pruning without updating parameters; unclear which axis to prune in conv layers (usually dim=0 for output channels).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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