huggingface/transformers · error · ValueError

out_features must be a subset of stage_names: {self.stage_na

Error message

out_features must be a subset of stage_names: {self.stage_names} got {self._out_features}

What it means

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.

Source

Thrown at src/transformers/backbone_utils.py:85

        elif out_features is None and out_indices is not None:
            out_features = [self.stage_names[idx] for idx in out_indices]

        # Update values and verify that the aligned out_features and out_indices are valid
        self._out_features, self._out_indices = out_features, out_indices
        self.verify_out_features_out_indices()

    def verify_out_features_out_indices(self):
        """
        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(

View on GitHub (pinned to a597f97485)

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

Example fix

// before
cfg = SomeBackboneConfig(out_features=["stem", "stage1", "stage2"])
// after
print(cfg.stage_names)  # e.g. ['stage1', 'stage2', 'stage3']
cfg = SomeBackboneConfig(out_features=["stage1", "stage2"])

Defensive patterns

Strategy: validation

Validate before calling

cfg = SomeBackboneConfig(...)
out_features = [f for f in out_features if f in cfg.stage_names]
# or fail loudly:
unknown = set(out_features) - set(cfg.stage_names)
if unknown:
    raise ValueError(f"Unknown stages {unknown}; valid: {cfg.stage_names}")

Type guard

def out_features_subset_of(cfg, out_features) -> bool:
    return out_features is None or set(out_features) <= set(cfg.stage_names)

Try / catch

try:
    cfg = SomeBackboneConfig(out_features=out_features)
except ValueError as e:
    if "must be a subset of stage_names" in str(e):
        # fall back to indices, which port across naming schemes
        cfg = SomeBackboneConfig(out_indices=[cfg.stage_names.index(f) for f in out_features if f in cfg.stage_names])
    else:
        raise

Prevention

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

When it happens

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

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

Related errors

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