{"record":{"id":"f8d68fcaf47ac460","repo":"huggingface/transformers","slug":"out-features-and-out-indices-should-correspond-to","errorCode":null,"errorMessage":"out_features and out_indices should correspond to the same stages if both are set","messagePattern":"out_features and out_indices should correspond to the same stages if both are set","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/backbone_utils.py","lineNumber":122,"sourceCode":"                    f\"out_indices must be valid indices for stage_names {self.stage_names}, got {self._out_indices}\"\n                )\n            if len(positive_indices) != len(set(positive_indices)):\n                msg = f\"out_indices must not contain any duplicates, got {self._out_indices}\"\n                msg += f\"(equivalent to {positive_indices}))\" if positive_indices != self._out_indices else \"\"\n                raise ValueError(msg)\n            if positive_indices != tuple(sorted(positive_indices)):\n                sorted_negative = [\n                    idx for _, idx in sorted(zip(positive_indices, self._out_indices), key=lambda x: x[0])\n                ]\n                raise ValueError(\n                    f\"out_indices must be in the same order as stage_names, expected {sorted_negative} got {self._out_indices}\"\n                )\n\n        if self._out_features is not None and self._out_indices is not None:\n            if len(self._out_features) != len(self._out_indices):\n                raise ValueError(\"out_features and out_indices should have the same length if both are set\")\n            if self._out_features != [self.stage_names[idx] for idx in self._out_indices]:\n                raise ValueError(\"out_features and out_indices should correspond to the same stages if both are set\")\n\n    @property\n    def out_features(self):\n        return self._out_features\n\n    @out_features.setter\n    def out_features(self, out_features: list[str]):\n        \"\"\"\n        Set the out_features attribute. This will also update the out_indices attribute to match the new out_features.\n        \"\"\"\n        self.set_output_features_output_indices(out_features=out_features, out_indices=None)\n\n    @property\n    def out_indices(self):\n        return self._out_indices\n\n    @out_indices.setter\n    def out_indices(self, out_indices: tuple[int, ...] | list[int]):","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/backbone_utils.py#L104-L140","documentation":"Raised when out_features and out_indices are both set, have equal length, but do not reference the same stages: mapping each index through stage_names must reproduce out_features exactly. This catches subtle desync where names and indices point at different stages (order and identity both matter).","triggerScenarios":"config.out_features = ['stage1', 'stage2'] with config.out_indices = [2, 1] (wrong stages / wrong order); any combination where [stage_names[i] for i in out_indices] != out_features. Fires at config verification during model init.","commonSituations":"Renaming or reordering stages in a custom backbone while keeping old indices; fine-tuning configs where only one attribute was edited; models whose timm stage names ('layer1') differ from transformers names ('stage1') and the user mixed vocabularies.","solutions":["Align them: out_indices = [config.stage_names.index(f) for f in out_features]","Or only set out_features and let the setter maintain out_indices","Verify vocabularies match: timm names (act/layer1..) never equal transformers names (stem/stage1..)"],"exampleFix":"# before\nconfig.out_features = ['stage1', 'stage2']\nconfig.out_indices = [2, 3]\n\n# after\nconfig.out_features = ['stage1', 'stage2']\nconfig.out_indices = [config.stage_names.index(f) for f in config.out_features]","handlingStrategy":"validation","validationCode":"if config.out_features is not None and config.out_indices is not None:\n    expected = [config.stage_names[i] for i in config.out_indices]\n    assert config.out_features == expected, f\"out_features {config.out_features} != stages at out_indices {expected}\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive out_indices from out_features via stage_names.index instead of maintaining both","Never mix timm-style names (layer1) with transformers-style names (stage1)","After any config surgery, call config.verify_out_features_out_indices() as a smoke test"],"tags":["config","backbone","validation","consistency"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}