{"record":{"id":"bfaa51dd168c2799","repo":"huggingface/transformers","slug":"out-features-must-be-in-the-same-order-as-stage-na","errorCode":null,"errorMessage":"out_features must be in the same order as stage_names, expected {sorted_feats} got {self._out_features}","messagePattern":"out_features must be in the same order as stage_names, expected (.+?) got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/backbone_utils.py","lineNumber":93,"sourceCode":"        \"\"\"\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(\n                    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 = [","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/backbone_utils.py#L75-L111","documentation":"Raised by BackboneConfigMixin.verify_out_features_out_indices when _out_features, while being a duplicate-free subset of stage_names, is not in the same relative order as stage_names. The check builds sorted_feats = [feat for feat in stage_names if feat in out_features] and compares; e.g. stage_names ['stage1','stage2','stage3'] with out_features ['stage3','stage1'] fails because a backbone cannot emit later stages before earlier ones.","triggerScenarios":"Passing out_features=[\"stage3\", \"stage1\"] or ['stage2', 'stage1'] to a config with ordered stage_names; also arises when out_indices are reordered by user code, since set_output_features_output_indices derives out_features from out_indices via stage_names[idx] in the given index order on the second verification pass.","commonSituations":"Users assuming out_features is an arbitrary selection set; sorting bugs (e.g. reversed() applied to the list); configs hand-crafted for multi-scale detection/segmentation necks where order was assumed irrelevant.","solutions":["Reorder out_features to follow stage order: ['stage1', 'stage3'] not ['stage3', 'stage1']","Sort programmatically against stage_names: out_features = [s for s in cfg.stage_names if s in set(out_features)]","If only the last stages are needed, use out_indices (e.g. [0, 2]) and let the mixin derive correctly ordered names"],"exampleFix":"// before\ncfg = SomeBackboneConfig(out_features=[\"stage3\", \"stage1\"])\n// after\ncfg = SomeBackboneConfig(out_features=[\"stage1\", \"stage3\"])","handlingStrategy":"validation","validationCode":"cfg = SomeBackboneConfig(...)\nout_features = [s for s in cfg.stage_names if s in set(out_features)]  # enforce stage order\ncfg = SomeBackboneConfig(out_features=out_features)","typeGuard":"def in_stage_order(cfg, out_features) -> bool:\n    if out_features is None:\n        return True\n    expected = [s for s in cfg.stage_names if s in set(out_features)]\n    return out_features == expected","tryCatchPattern":"try:\n    cfg = SomeBackboneConfig(out_features=out_features)\nexcept ValueError as e:\n    if \"same order as stage_names\" in str(e):\n        ordered = [s for s in cfg.stage_names if s in set(out_features)]\n        cfg = SomeBackboneConfig(out_features=ordered)\n    else:\n        raise","preventionTips":["out_features is order-sensitive: always list stages in network execution order","Derive the list by filtering stage_names rather than writing it by hand","out_indices must likewise be increasing (negative indices are normalized first)"],"tags":["backbone","configuration","validation","ordering"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}