What causes "Exporter must extend HfExporter" in huggingface/transformers?

Make the decorated class inherit from HfExporter: class MyExporter(HfExporter): ... and implement export().

huggingface/transformers · error · TypeError

Exporter must extend HfExporter

Error message

Exporter must extend HfExporter

What it means

The @register_exporter(name) decorator raises TypeError when the decorated class is not a subclass of HfExporter. The registry stores factory classes that must implement the abstract exporter interface (dependency checks, export, export_for_generation), so anything else would break AutoHfExporter.from_config at instantiation time.

Source

Thrown at src/transformers/exporters/auto.py:165

                f"Export format {name!r} has a registered exporter but no config class. "
                f"Register one via ``@register_export_config({name!r})``. Skipping."
            )
            return False
        if not has_exporter:
            logger.warning(
                f"Export format {name!r} has a registered config class but no exporter. "
                f"Register one via ``@register_exporter({name!r})``. Skipping."
            )
            return False
        return True


def register_exporter(name: str):
    def register_exporter_fn(cls):
        if name in AUTO_EXPORTER_MAPPING:
            logger.warning(f"Exporter '{name}' is already registered and will be overwritten.")
        if not issubclass(cls, HfExporter):
            raise TypeError("Exporter must extend HfExporter")
        AUTO_EXPORTER_MAPPING[name] = cls
        return cls

    return register_exporter_fn


def register_export_config(name: str):
    def register_export_config_fn(cls):
        if name in AUTO_EXPORT_CONFIG_MAPPING:
            logger.warning(f"Export config '{name}' is already registered and will be overwritten.")
        if not issubclass(cls, ExportConfigMixin):
            raise TypeError("Export config must extend ExportConfigMixin")
        AUTO_EXPORT_CONFIG_MAPPING[name] = cls
        return cls

    return register_export_config_fn

View on GitHub (pinned to a597f97485)

Solutions

Make the decorated class inherit from HfExporter: class MyExporter(HfExporter): ... and implement export().
If you only want a config (no custom exporter), use @register_export_config instead.
Verify with issubclass(MyExporter, HfExporter) before decorating.

Example fix

# before
@register_exporter("trt")
class TrtExporter:  # TypeError
    ...

# after
from transformers.exporters.base import HfExporter

@register_exporter("trt")
class TrtExporter(HfExporter):
    def export(self, model, sample_inputs, config): ...

Defensive patterns

Strategy: type-guard

Validate before calling

from transformers.exporters.base import HfExporter

assert issubclass(MyExporter, HfExporter), "custom exporters must subclass HfExporter"
register_exporter("mybackend")(MyExporter)

Type guard

def is_valid_exporter(cls) -> bool:
    from transformers.exporters.base import HfExporter
    return isinstance(cls, type) and issubclass(cls, HfExporter)

Prevention

Import HfExporter in the same module where you define custom exporters so the inheritance is visible
Add a unit test asserting your plugin registers cleanly (decorator raises TypeError at import time otherwise)

When it happens

Trigger: Applying @register_exporter("mybackend") to a plain class, a function-style wrapper, or a class inheriting only from object; multiple inheritance where HfExporter is not in the MRO.

Common situations: Writing a custom backend (TensorRT, TFLite, CoreML) and wiring it into the auto-factory; refactoring an existing exporter so it no longer inherits HfExporter.

Related errors

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