huggingface/transformers · error · ValueError

Config has `stage_names` set to {stage_names_from_config} wh

Error message

Config has `stage_names` set to {stage_names_from_config} which doesn't match `stage_names` from backbone's feature_info. Please check if your checkpoint has correct `stage_names` saved.

What it means

Raised in _init_timm_backbone when config.stage_names (if set) does not equal [stage['module'] for stage in backbone.feature_info.info] — the stage names reported by the instantiated timm backbone. Like the out_features check, this catches configs authored for (or mutated against) a different backbone implementation or a different timm model than the one being constructed. After the checks pass, the config's stage_names is overwritten with the timm-derived names.

Source

Thrown at src/transformers/backbone_utils.py:243

        stage_names_from_config = getattr(self.config, "stage_names", None)

        # These will disagree with the defaults for the transformers models e.g. for resnet50
        # the transformer model has out_features = ['stem', 'stage1', 'stage2', 'stage3', 'stage4']
        # the timm model has out_features = ['act', 'layer1', 'layer2', 'layer3', 'layer4']
        self.stage_names = [stage["module"] for stage in backbone.feature_info.info]
        self.num_features = [stage["num_chs"] for stage in backbone.feature_info.info]

        out_indices = list(backbone.feature_info.out_indices)
        out_features = backbone.feature_info.module_name()

        if out_features_from_config is not None and out_features_from_config != out_features:
            raise ValueError(
                f"Config has `out_features` set to {out_features_from_config} which doesn't match `out_features` "
                "from backbone's feature_info. Please check if your checkpoint has correct out features/indices saved."
            )

        if stage_names_from_config is not None and stage_names_from_config != self.stage_names:
            raise ValueError(
                f"Config has `stage_names` set to {stage_names_from_config} which doesn't match `stage_names` "
                "from backbone's feature_info. Please check if your checkpoint has correct `stage_names` saved."
            )

        # We set, align and verify out indices, out features and stage names
        self.config.stage_names = self.stage_names
        self.config.set_output_features_output_indices(out_features, out_indices)

    def _init_transformers_backbone(self) -> None:
        self.stage_names = self.config.stage_names
        self.config.verify_out_features_out_indices()
        # Number of channels for each stage. This is set in the transformer backbone model init
        self.num_features = None

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

View on GitHub (pinned to a597f97485)

Solutions

Clear the stale value: config.stage_names = None before constructing the timm backbone
Ensure the config actually corresponds to the backbone= argument you pass to the timm model
Regenerate the config from AutoConfig.for_model(...) / the intended checkpoint

Example fix

# before
config.stage_names = ['stem', 'stage1', 'stage2', 'stage3', 'stage4']
model = TimmBackbone(config, backbone='resnet50')

# after
config.stage_names = None  # let feature_info define stage names
model = TimmBackbone(config, backbone='resnet50')

Defensive patterns

Strategy: validation

Validate before calling

if use_timm_backend and getattr(config, 'stage_names', None) is not None:
    timm_names = [s['module'] for s in timm.create_model(name, pretrained=False).feature_info.info]
    if config.stage_names != timm_names:
        config.stage_names = None  # defer to feature_info

Try / catch

try:
    backbone = TimmBackbone(config, backbone=name)
except ValueError as e:
    if 'stage_names' in str(e):
        config.stage_names = None
        backbone = TimmBackbone(config, backbone=name)
    else:
        raise

Prevention

Clear stage_names when reusing a config across backbones or model variants
Load configs with AutoConfig.from_pretrained(checkpoint) matched to the same checkpoint's backbone
Treat stage_names as derived state owned by the backbone, not user input

When it happens

Trigger: Loading a timm-backed model whose config carries transformers-style stage_names; passing a backbone='resnet50' with a config built for a different architecture (e.g. saved from resnet152 with more stages); hand-editing stage_names.

Common situations: Cross-implementation migration (transformers-native <-> timm backend); checkpoint reuse across model variants of the same family; configs serialized before stage_names were auto-managed.

Related errors

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