Lightning-AI/pytorch-lightning · error · MisconfigurationException

The LightningModule should have a nn.Module `backbone` attri

Error message

The LightningModule should have a nn.Module `backbone` attribute

What it means

BackboneFinetuning requires the LightningModule to expose an attribute named `backbone` that is an `nn.Module` so it can freeze/unfreeze it. `on_fit_start` checks `hasattr(pl_module, 'backbone') and isinstance(pl_module.backbone, Module)` and raises MisconfigurationException otherwise.

Source

Thrown at src/lightning/pytorch/callbacks/finetuning.py:454

            "internal_optimizer_metadata": self._internal_optimizer_metadata,
            "previous_backbone_lr": self.previous_backbone_lr,
        }

    @override
    def load_state_dict(self, state_dict: dict[str, Any]) -> None:
        self.previous_backbone_lr = state_dict["previous_backbone_lr"]
        super().load_state_dict(state_dict)

    @override
    def on_fit_start(self, trainer: "pl.Trainer", pl_module: "pl.LightningModule") -> None:
        """
        Raises:
            MisconfigurationException:
                If LightningModule has no nn.Module `backbone` attribute.
        """
        if hasattr(pl_module, "backbone") and isinstance(pl_module.backbone, Module):
            return super().on_fit_start(trainer, pl_module)
        raise MisconfigurationException("The LightningModule should have a nn.Module `backbone` attribute")

    @override
    def freeze_before_training(self, pl_module: "pl.LightningModule") -> None:
        self.freeze(pl_module.backbone)

    @override
    def finetune_function(self, pl_module: "pl.LightningModule", epoch: int, optimizer: Optimizer) -> None:
        """Called when the epoch begins."""
        if epoch == self.unfreeze_backbone_at_epoch:
            current_lr = optimizer.param_groups[0]["lr"]
            initial_backbone_lr = (
                self.backbone_initial_lr
                if self.backbone_initial_lr is not None
                else current_lr * self.backbone_initial_ratio_lr
            )
            self.previous_backbone_lr = initial_backbone_lr
            self.unfreeze_and_add_param_group(
                pl_module.backbone,

View on GitHub (pinned to 9fed5c27d2)

Solutions

1. Name the submodule `self.backbone = ...` in your LightningModule
2. Or subclass BaseFinetuning and implement freeze logic targeting your actual attribute name
3. If `backbone` is a property, make sure it returns an nn.Module instance

Example fix

# before
class LM(LightningModule):
    def __init__(self): self.encoder = resnet18()
# after
class LM(LightningModule):
    def __init__(self): self.backbone = resnet18()

from torch import nn
assert hasattr(model, 'backbone') and isinstance(getattr(model, 'backbone', None), nn.Module), \
    'BackboneFinetuning requires a nn.Module attribute named backbone'

from torch import nn
def has_backbone(pl_module) -> bool:
    return isinstance(getattr(pl_module, 'backbone', None), nn.Module)

When it happens

Trigger: Using `BackboneFinetuning` when the model's submodule is named `model`, `encoder`, `feature_extractor`, etc., or when `backbone` is a plain Python object / property returning a non-Module.

Common situations: Wrapping a HuggingFace model (`self.model = ...`) instead of `self.backbone`; renaming attributes during a refactor; backbone stored in a dict or list rather than as a direct attribute.

Related errors

• The Finetuning callback does not support running with the De
• Received multiple values for {', '.join(duplicated_plugin_ke
• Received both `precision={precision_input}` and `plugins={se
• accelerator set through both strategy class and accelerator
• precision set through both strategy class and plugins, choos

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