huggingface/transformers · error · ValueError

out_features and out_indices should correspond to the same s

Error message

out_features and out_indices should correspond to the same stages if both are set

What it means

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).

Source

Thrown at src/transformers/backbone_utils.py:122

                    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 = [
                    idx for _, idx in sorted(zip(positive_indices, self._out_indices), key=lambda x: x[0])
                ]
                raise ValueError(
                    f"out_indices must be in the same order as stage_names, expected {sorted_negative} got {self._out_indices}"
                )

        if self._out_features is not None and self._out_indices is not None:
            if len(self._out_features) != len(self._out_indices):
                raise ValueError("out_features and out_indices should have the same length if both are set")
            if self._out_features != [self.stage_names[idx] for idx in self._out_indices]:
                raise ValueError("out_features and out_indices should correspond to the same stages if both are set")

    @property
    def out_features(self):
        return self._out_features

    @out_features.setter
    def out_features(self, out_features: list[str]):
        """
        Set the out_features attribute. This will also update the out_indices attribute to match the new out_features.
        """
        self.set_output_features_output_indices(out_features=out_features, out_indices=None)

    @property
    def out_indices(self):
        return self._out_indices

    @out_indices.setter
    def out_indices(self, out_indices: tuple[int, ...] | list[int]):

View on GitHub (pinned to a597f97485)

Solutions

1. Align them: out_indices = [config.stage_names.index(f) for f in out_features]
2. Or only set out_features and let the setter maintain out_indices
3. Verify vocabularies match: timm names (act/layer1..) never equal transformers names (stem/stage1..)

Example fix

# before
config.out_features = ['stage1', 'stage2']
config.out_indices = [2, 3]

# after
config.out_features = ['stage1', 'stage2']
config.out_indices = [config.stage_names.index(f) for f in config.out_features]

if config.out_features is not None and config.out_indices is not None:
    expected = [config.stage_names[i] for i in config.out_indices]
    assert config.out_features == expected, f"out_features {config.out_features} != stages at out_indices {expected}"

When it happens

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

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

Related errors

• out_features and out_indices should have the same length if
• out_indices must be a list, got {type(self._out_indices)}
• out_indices must be valid indices for stage_names {self.stag
• out_indices must not contain any duplicates, got {self._out_
• out_indices must be in the same order as stage_names, expect

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