{"record":{"id":"048f37135985a8ce","repo":"Lightning-AI/pytorch-lightning","slug":"the-lightningmodule-should-have-a-nn-module-backb","errorCode":null,"errorMessage":"The LightningModule should have a nn.Module `backbone` attribute","messagePattern":"The LightningModule should have a nn\\.Module `backbone` attribute","errorType":"validation","errorClass":"MisconfigurationException","httpStatus":null,"severity":"error","filePath":"src/lightning/pytorch/callbacks/finetuning.py","lineNumber":454,"sourceCode":"            \"internal_optimizer_metadata\": self._internal_optimizer_metadata,\n            \"previous_backbone_lr\": self.previous_backbone_lr,\n        }\n\n    @override\n    def load_state_dict(self, state_dict: dict[str, Any]) -> None:\n        self.previous_backbone_lr = state_dict[\"previous_backbone_lr\"]\n        super().load_state_dict(state_dict)\n\n    @override\n    def on_fit_start(self, trainer: \"pl.Trainer\", pl_module: \"pl.LightningModule\") -> None:\n        \"\"\"\n        Raises:\n            MisconfigurationException:\n                If LightningModule has no nn.Module `backbone` attribute.\n        \"\"\"\n        if hasattr(pl_module, \"backbone\") and isinstance(pl_module.backbone, Module):\n            return super().on_fit_start(trainer, pl_module)\n        raise MisconfigurationException(\"The LightningModule should have a nn.Module `backbone` attribute\")\n\n    @override\n    def freeze_before_training(self, pl_module: \"pl.LightningModule\") -> None:\n        self.freeze(pl_module.backbone)\n\n    @override\n    def finetune_function(self, pl_module: \"pl.LightningModule\", epoch: int, optimizer: Optimizer) -> None:\n        \"\"\"Called when the epoch begins.\"\"\"\n        if epoch == self.unfreeze_backbone_at_epoch:\n            current_lr = optimizer.param_groups[0][\"lr\"]\n            initial_backbone_lr = (\n                self.backbone_initial_lr\n                if self.backbone_initial_lr is not None\n                else current_lr * self.backbone_initial_ratio_lr\n            )\n            self.previous_backbone_lr = initial_backbone_lr\n            self.unfreeze_and_add_param_group(\n                pl_module.backbone,","sourceCodeStart":436,"sourceCodeEnd":472,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/pytorch/callbacks/finetuning.py#L436-L472","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Name the submodule `self.backbone = ...` in your LightningModule","Or subclass BaseFinetuning and implement freeze logic targeting your actual attribute name","If `backbone` is a property, make sure it returns an nn.Module instance"],"exampleFix":"# before\nclass LM(LightningModule):\n    def __init__(self): self.encoder = resnet18()\n# after\nclass LM(LightningModule):\n    def __init__(self): self.backbone = resnet18()","handlingStrategy":"validation","validationCode":"from torch import nn\nassert hasattr(model, 'backbone') and isinstance(getattr(model, 'backbone', None), nn.Module), \\\n    'BackboneFinetuning requires a nn.Module attribute named backbone'","typeGuard":"from torch import nn\ndef has_backbone(pl_module) -> bool:\n    return isinstance(getattr(pl_module, 'backbone', None), nn.Module)","tryCatchPattern":null,"preventionTips":["Adopt a project convention naming the feature extractor `self.backbone`","Assert the attribute before constructing BackboneFinetuning in shared training scripts"],"tags":["lightning","finetuning","backbone","attribute-missing"],"backgroundTag":"missing-required-attribute","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}