huggingface/transformers · error · ValueError

out_indices must be a list, got {type(self._out_indices)}

Error message

out_indices must be a list, got {type(self._out_indices)}

What it means

Thrown by BackboneConfigMixin.verify_out_features_out_indices (via _out_indices validation) when the config's out_indices attribute is not a Python list. The library requires out_indices to be a plain list because subsequent validation iterates it, computes set() for duplicates, and zips it against out_features — all list assumptions. Typical cause is passing a tuple, numpy array, or int.

Source

Thrown at src/transformers/backbone_utils.py:99

        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 = [
                    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}"
                )

View on GitHub (pinned to a597f97485)

Solutions

  1. Pass out_indices as a plain Python list: out_indices=[1, 2]
  2. Convert before assigning: config.out_indices = list(your_indices)
  3. If loading from a checkpoint/dict, coerce: out_indices = list(raw.get('out_indices', []))

Example fix

# before
config.out_indices = (1, 2)  # tuple -> ValueError

# after
config.out_indices = [1, 2]  # list
Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(out_indices, list):
    out_indices = list(out_indices)
assert isinstance(out_indices, list), "out_indices must be a list"

Type guard

def is_valid_out_indices(v) -> bool:
    return isinstance(v, list) and all(isinstance(i, int) for i in v)

Try / catch

try:
    config.verify_out_features_out_indices()
except ValueError as e:
    raise ValueError(f"Invalid backbone output config: {e}") from e

Prevention

When it happens

Trigger: Setting out_indices as a tuple (out_indices=(1, 2)), numpy array (out_indices=np.array([1,2])), a single int (out_indices=3), or None-like scalars in a backbone config (e.g. TimmBackboneConfig or any *BackboneConfiguration), then instantiating the model or calling config.verify_out_features_out_indices().

Common situations: Users copy out_indices from a timm config or a JSON checkpoint where it was serialized as a tuple; users coming from other APIs that accept tuples; programmatic config building that reuses numpy index arrays.

Related errors

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