huggingface/transformers · error · ValueError

out_features must be in the same order as stage_names, expec

Error message

out_features must be in the same order as stage_names, expected {sorted_feats} got {self._out_features}

What it means

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.

Source

Thrown at src/transformers/backbone_utils.py:93

        """
        Verify that out_indices and out_features are valid for the given stage_names.
        """
        if self.stage_names is None:
            raise ValueError("Stage_names must be set for transformers backbones")

        if self._out_features is not None:
            if not isinstance(self._out_features, (list,)):
                raise ValueError(f"out_features must be a list got {type(self._out_features)}")
            if any(feat not in self.stage_names for feat in self._out_features):
                raise ValueError(
                    f"out_features must be a subset of stage_names: {self.stage_names} got {self._out_features}"
                )
            if len(self._out_features) != len(set(self._out_features)):
                raise ValueError(f"out_features must not contain any duplicates, got {self._out_features}")
            if self._out_features != (
                sorted_feats := [feat for feat in self.stage_names if feat in self._out_features]
            ):
                raise ValueError(
                    f"out_features must be in the same order as stage_names, expected {sorted_feats} got {self._out_features}"
                )

        if self._out_indices is not None:
            if not isinstance(self._out_indices, list):
                raise ValueError(f"out_indices must be a list, got {type(self._out_indices)}")
            # Convert negative indices to their positive equivalent: [-1,] -> [len(stage_names) - 1,]
            positive_indices = tuple(idx % len(self.stage_names) if idx < 0 else idx for idx in self._out_indices)
            if any(idx for idx in positive_indices if idx not in range(len(self.stage_names))):
                raise ValueError(
                    f"out_indices must be valid indices for stage_names {self.stage_names}, got {self._out_indices}"
                )
            if len(positive_indices) != len(set(positive_indices)):
                msg = f"out_indices must not contain any duplicates, got {self._out_indices}"
                msg += f"(equivalent to {positive_indices}))" if positive_indices != self._out_indices else ""
                raise ValueError(msg)
            if positive_indices != tuple(sorted(positive_indices)):
                sorted_negative = [

View on GitHub (pinned to a597f97485)

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

Example fix

// before
cfg = SomeBackboneConfig(out_features=["stage3", "stage1"])
// after
cfg = SomeBackboneConfig(out_features=["stage1", "stage3"])

Defensive patterns

Strategy: validation

Validate before calling

cfg = SomeBackboneConfig(...)
out_features = [s for s in cfg.stage_names if s in set(out_features)]  # enforce stage order
cfg = SomeBackboneConfig(out_features=out_features)

Type guard

def in_stage_order(cfg, out_features) -> bool:
    if out_features is None:
        return True
    expected = [s for s in cfg.stage_names if s in set(out_features)]
    return out_features == expected

Try / catch

try:
    cfg = SomeBackboneConfig(out_features=out_features)
except ValueError as e:
    if "same order as stage_names" in str(e):
        ordered = [s for s in cfg.stage_names if s in set(out_features)]
        cfg = SomeBackboneConfig(out_features=ordered)
    else:
        raise

Prevention

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)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/bfaa51dd168c2799. Report an issue: GitHub.