{"record":{"id":"575ecc6fe3da1fd9","repo":"huggingface/transformers","slug":"out-features-must-be-a-subset-of-stage-names-sel","errorCode":null,"errorMessage":"out_features must be a subset of stage_names: {self.stage_names} got {self._out_features}","messagePattern":"out_features must be a subset of stage_names: (.+?) got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/backbone_utils.py","lineNumber":85,"sourceCode":"        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:\n            if not isinstance(self._out_indices, list):\n                raise ValueError(f\"out_indices must be a list, got {type(self._out_indices)}\")\n            # Convert negative indices to their positive equivalent: [-1,] -> [len(stage_names) - 1,]\n            positive_indices = tuple(idx % len(self.stage_names) if idx < 0 else idx for idx in self._out_indices)\n            if any(idx for idx in positive_indices if idx not in range(len(self.stage_names))):\n                raise ValueError(","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/backbone_utils.py#L67-L103","documentation":"Raised by BackboneConfigMixin.verify_out_features_out_indices when any entry in self._out_features is not a member of self.stage_names. out_features selects which backbone stages are returned as feature maps, so every name must exactly match a stage name defined by the config; the error message prints both the valid stage_names and the offending out_features to help spot typos.","triggerScenarios":"Passing names from a different backbone family, e.g. out_features=[\"stem\", \"stage1\", \"stage2\"] to a config whose stage_names are [\"stage1\", \"stage2\", \"stage3\"]; using indices as strings like \"0\"; casing or spelling mismatches such as \"Stage1\" or \"stage_1\".","commonSituations":"Copying out_features from another model's config or paper; upgrading transformers versions where a model's stage naming scheme changed; writing configs by hand without checking the backbone's stage_names attribute.","solutions":["Print config.stage_names first and use exactly those names in out_features","Use out_indices (integers) instead of names when porting configs between models with different naming","Diff the old/new stage naming after a library upgrade and remap out_features accordingly"],"exampleFix":"// before\ncfg = SomeBackboneConfig(out_features=[\"stem\", \"stage1\", \"stage2\"])\n// after\nprint(cfg.stage_names)  # e.g. ['stage1', 'stage2', 'stage3']\ncfg = SomeBackboneConfig(out_features=[\"stage1\", \"stage2\"])","handlingStrategy":"validation","validationCode":"cfg = SomeBackboneConfig(...)\nout_features = [f for f in out_features if f in cfg.stage_names]\n# or fail loudly:\nunknown = set(out_features) - set(cfg.stage_names)\nif unknown:\n    raise ValueError(f\"Unknown stages {unknown}; valid: {cfg.stage_names}\")","typeGuard":"def out_features_subset_of(cfg, out_features) -> bool:\n    return out_features is None or set(out_features) <= set(cfg.stage_names)","tryCatchPattern":"try:\n    cfg = SomeBackboneConfig(out_features=out_features)\nexcept ValueError as e:\n    if \"must be a subset of stage_names\" in str(e):\n        # fall back to indices, which port across naming schemes\n        cfg = SomeBackboneConfig(out_indices=[cfg.stage_names.index(f) for f in out_features if f in cfg.stage_names])\n    else:\n        raise","preventionTips":["Print cfg.stage_names before hand-writing out_features","Prefer out_indices when porting configs across model families","Re-check stage naming after upgrading transformers"],"tags":["backbone","configuration","validation","naming"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}