{"record":{"id":"8b81897ac84cd5da","repo":"huggingface/transformers","slug":"stage-names-must-be-set-for-transformers-backbones","errorCode":null,"errorMessage":"Stage_names must be set for transformers backbones","messagePattern":"Stage_names must be set for transformers backbones","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/backbone_utils.py","lineNumber":79,"sourceCode":"        out_features, out_indices = self._out_features, self._out_indices\n        if out_indices is None and out_features is None:\n            out_indices = [len(self.stage_names) - 1]\n            out_features = [self.stage_names[-1]]\n        elif out_indices is None and out_features is not None:\n            out_indices = [self.stage_names.index(layer) for layer in out_features]\n        elif out_features is None and out_indices is not None:\n            out_features = [self.stage_names[idx] for idx in out_indices]\n\n        # Update values and verify that the aligned out_features and out_indices are valid\n        self._out_features, self._out_indices = out_features, out_indices\n        self.verify_out_features_out_indices()\n\n    def verify_out_features_out_indices(self):\n        \"\"\"\n        Verify that out_indices and out_features are valid for the given stage_names.\n        \"\"\"\n        if self.stage_names is None:\n            raise ValueError(\"Stage_names must be set for transformers backbones\")\n\n        if self._out_features is not None:\n            if not isinstance(self._out_features, (list,)):\n                raise ValueError(f\"out_features must be a list got {type(self._out_features)}\")\n            if any(feat not in self.stage_names for feat in self._out_features):\n                raise ValueError(\n                    f\"out_features must be a subset of stage_names: {self.stage_names} got {self._out_features}\"\n                )\n            if len(self._out_features) != len(set(self._out_features)):\n                raise ValueError(f\"out_features must not contain any duplicates, got {self._out_features}\")\n            if self._out_features != (\n                sorted_feats := [feat for feat in self.stage_names if feat in self._out_features]\n            ):\n                raise ValueError(\n                    f\"out_features must be in the same order as stage_names, expected {sorted_feats} got {self._out_features}\"\n                )\n\n        if self._out_indices is not None:","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/backbone_utils.py#L61-L97","documentation":"Raised by BackboneConfigMixin.verify_out_features_out_indices when self.stage_names is None. Every transformers-style backbone (e.g. Swin, Beit, ViT hybrids) must define an ordered list of stage names; out_features/out_indices alignment (set_output_features_output_indices) indexes into stage_names, so a missing list makes the whole scheme unusable. It fires on the first verification pass, before any out_features logic.","triggerScenarios":"Instantiating a backbone config that inherits BackboneConfigMixin but never sets stage_names (custom/new backbone implementations); calling config.set_output_features_output_indices(...) on such a config; loading a checkpoint whose config class forgot stage_names in its __init__.","commonSituations":"Authors of new model backbones who copy the mixin but skip defining stage_names; subclasses that override __init__ without calling super or without populating stage_names; serialization edge cases where stage_names was dropped from the config dict.","solutions":["Define stage_names in the config class, e.g. self.stage_names = [f'stage{i}' for i in range(num_stages)] before calling set_output_features_output_indices","If subclassing an existing backbone config, do not overwrite stage_names with None; reuse the parent's list or extend it","When loading, pass stage_names explicitly if the checkpoint config predates the attribute: BackboneConfig.from_pretrained(..., stage_names=[...])"],"exampleFix":"// before\nclass MyBackboneConfig(BackboneConfigMixin):\n    def __init__(self, **kwargs):\n        super().__init__(**kwargs)\n        # stage_names never set\n        self.set_output_features_output_indices(None, None)\n// after\nclass MyBackboneConfig(BackboneConfigMixin):\n    def __init__(self, **kwargs):\n        super().__init__(**kwargs)\n        self.stage_names = [f\"stage{i}\" for i in range(self.num_stages)]\n        self.set_output_features_output_indices(None, None)","handlingStrategy":"validation","validationCode":"cfg = MyBackboneConfig(...)\nif getattr(cfg, \"stage_names\", None) is None:\n    cfg.stage_names = [f\"stage{i}\" for i in range(cfg.num_stages)]\ncfg.set_output_features_output_indices(out_features, out_indices)","typeGuard":"def has_stage_names(cfg) -> bool:\n    names = getattr(cfg, \"stage_names\", None)\n    return isinstance(names, (list, tuple)) and len(names) > 0 and all(isinstance(n, str) for n in names)","tryCatchPattern":"try:\n    cfg.set_output_features_output_indices(out_features, out_indices)\nexcept ValueError as e:\n    if \"Stage_names must be set\" in str(e):\n        raise TypeError(\"MyBackboneConfig must define stage_names before use\") from e\n    raise","preventionTips":["Every BackboneConfigMixin subclass must assign stage_names in __init__","When subclassing an existing backbone config, reuse or extend the parent's stage_names","Add an init-time assertion: assert self.stage_names is not None"],"tags":["backbone","configuration","validation","computer-vision"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}