What causes "This method should be implemented by the derived class." in huggingface/transformers?

Implement forward(self, pixel_values, **kwargs) in your backbone subclass returning feature maps or a BackboneOutput

huggingface/transformers · error · NotImplementedError

This method should be implemented by the derived class.

Error message

This method should be implemented by the derived class.

What it means

BackboneMixin.forward is an abstract stub: every concrete backbone must override it, because the mixin only supplies hooks, output capturing, and backbone-type plumbing — not the actual forward computation. If a derived class fails to override forward (or a caller invokes BackboneMixin.forward directly), this NotImplementedError fires. In older versions the mixin's forward was usable and warned; subclasses relying on that now break.

Source

Thrown at src/transformers/backbone_utils.py:305

    def channels(self):
        return [self.out_feature_channels[name] for name in self.out_features]

    def forward_with_filtered_kwargs(self, *args, **kwargs):
        if not self.has_attentions:
            kwargs.pop("output_attentions", None)
        if self.backbone_type == BackboneType.TIMM:
            signature = dict(inspect.signature(self.forward).parameters)
            kwargs = {k: v for k, v in kwargs.items() if k in signature}
        return self(*args, **kwargs)

    def forward(
        self,
        pixel_values,
        output_hidden_states: bool | None = None,
        output_attentions: bool | None = None,
        return_dict: bool | None = None,
    ):
        raise NotImplementedError("This method should be implemented by the derived class.")


def consolidate_backbone_kwargs_to_config(
    backbone_config,
    default_backbone: str | None = None,
    default_config_type: str | None = None,
    default_config_kwargs: dict | None = None,
    timm_default_kwargs: dict | None = None,
    **kwargs,
):
    # Lazy import to avoid circular import issues. Can be imported properly
    # after deleting ref to `BackboneMixin` in `utils/backbone_utils.py`
    from .configuration_utils import PreTrainedConfig
    from .models.auto import CONFIG_MAPPING

    use_timm_backbone = kwargs.pop("use_timm_backbone", True)
    backbone_kwargs = kwargs.pop("backbone_kwargs", {})
    backbone = kwargs.pop("backbone") if kwargs.get("backbone") is not None else default_backbone

View on GitHub (pinned to a597f97485)

Solutions

Implement forward(self, pixel_values, **kwargs) in your backbone subclass returning feature maps or a BackboneOutput
If you wanted a ready-made backbone, instantiate an existing one (e.g. AutoBackbone.from_pretrained(...)) instead of the bare mixin
Check for misspelled method names (foward) or decorators that hide the method

Example fix

# before
class MyBackbone(BackboneMixin, PreTrainedModel):
    pass  # no forward -> NotImplementedError

# after
class MyBackbone(BackboneMixin, PreTrainedModel):
    def forward(self, pixel_values):
        feature_maps = self.embedder(pixel_values)
        for stage in self.stages:
            feature_maps = stage(feature_maps)
        return feature_maps

Defensive patterns

Strategy: type-guard

Validate before calling

assert type(model).forward is not BackboneMixin.forward, "subclass must override forward()"

Type guard

def implements_forward(cls) -> bool:
    return 'forward' in cls.__dict__ or any('forward' in c.__dict__ for c in cls.__mro__[1:] if c is not BackboneMixin)

Try / catch

try:
    out = model(pixel_values)
except NotImplementedError:
    raise TypeError(f"{type(model).__name__} does not implement forward(); use a concrete backbone or AutoBackbone") from None

Prevention

Always define forward() in custom BackboneMixin subclasses
Prefer AutoBackbone.from_pretrained(...) over hand-rolled mixin usage
Run a single dummy forward in your model's __init__ or test suite to catch missing overrides early

When it happens

Trigger: Defining a class that inherits BackboneMixin (directly, without a concrete backbone base) and calling model(pixel_values); calling BackboneMixin.forward(model, ...) unbound; a custom backbone subclass whose forward was accidentally renamed or decorated away.

Common situations: Research code subclassing PreTrainedModel + BackboneMixin manually for a new architecture; upgrading transformers where a previously working mixin-level forward was removed; typos like def foward(self, ...).

Related errors

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