huggingface/transformers · error · ValueError

Unsupported backend {config.backend} for ExecuTorch export

Error message

Unsupported backend {config.backend} for ExecuTorch export

What it means

ExecutorchExporter.export looks up config.backend in the _BACKEND_PREPARE registry (which maps backend names to preparation functions; 'xnnpack' and 'cuda' are the shipped entries). An unknown backend name has no preparation/partitioner pipeline, so the export is rejected immediately with this ValueError.

Source

Thrown at src/transformers/exporters/exporter_executorch.py:140

    required_packages = ["torch", "executorch"]
    tested_versions = {"torch": "2.12.0", "executorch": "1.3.1"}

    def export(
        self,
        model: PreTrainedModel,
        sample_inputs: MutableMapping[str, Any],
        config: ExecutorchConfig | dict[str, Any],
    ) -> ExecutorchProgramManager:
        """Export a model to ExecuTorch, applying backend preparation and torch op patches."""
        if isinstance(config, dict):
            config = ExecutorchConfig(**config)
        elif type(config) is not ExecutorchConfig:
            raise TypeError(f"Expected config to be an ExecutorchConfig or dict, got {type(config)}")

        prepare_for_backend = _BACKEND_PREPARE.get(config.backend)
        if prepare_for_backend is None:
            raise ValueError(f"Unsupported backend {config.backend} for ExecuTorch export")

        model, sample_inputs, partitioner = prepare_for_backend(model, sample_inputs)

        with apply_patches("executorch"), apply_patches(f"executorch.{config.backend}"):
            exported_program: ExportedProgram = super().export(model, sample_inputs, config=config)
            apply_fx_program_fixes("executorch", exported_program)
            apply_fx_node_fixes("executorch", exported_program.graph_module)
            edge_program_manager: EdgeProgramManager = to_edge_transform_and_lower(
                exported_program, partitioner=partitioner, compile_config=_get_edge_compile_config()
            )
            executorch_programs_manager: ExecutorchProgramManager = edge_program_manager.to_executorch(
                config=_get_backend_config(config)
            )

        return executorch_programs_manager


def _get_edge_compile_config() -> EdgeCompileConfig:

View on GitHub (pinned to a597f97485)

Solutions

  1. Use a shipped backend: backend="xnnpack" (CPU) or backend="cuda" (GPU via AOTInductor).
  2. Check spelling/case — keys are lowercase in _BACKEND_PREPARE.
  3. For an unshipped backend, export with DynamoExporter first and lower to your backend with the raw torch.export/ExecuTorch API, or contribute a prepare function and extend _BACKEND_PREPARE.

Example fix

# before
ExecutorchConfig(backend="XNNPACK")  # ValueError: Unsupported backend

# after
ExecutorchConfig(backend="xnnpack")
Defensive patterns

Strategy: validation

Validate before calling

from transformers.exporters.exporter_executorch import _BACKEND_PREPARE

backend = cfg.get("backend", "xnnpack") if isinstance(cfg, dict) else cfg.backend
if backend not in _BACKEND_PREPARE:
    raise SystemExit(f"backend must be one of {sorted(_BACKEND_PREPARE)}, got {backend!r}")

Type guard

def is_supported_executorch_backend(backend: str) -> bool:
    from transformers.exporters.exporter_executorch import _BACKEND_PREPARE
    return backend in _BACKEND_PREPARE

Try / catch

try:
    ExecutorchExporter().export(model, inputs, cfg)
except ValueError as e:
    if "Unsupported backend" in str(e):
        cfg = ExecutorchConfig(**{**vars(cfg) if hasattr(cfg, "__dict__") else cfg, "backend": "xnnpack"})
        ExecutorchExporter().export(model, inputs, cfg)  # fall back to CPU backend
    else:
        raise

Prevention

When it happens

Trigger: Setting ExecutorchConfig(backend="coreml"), "qnn", "mps", "vulkan", or any typo like "XNNPACK" (case-sensitive) — no prepare function exists for it.

Common situations: Porting an ExecuTorch tutorial that targets a backend transformers does not ship prepare hooks for; casing mismatches; assuming every executorch backend from the upstream delegate list is supported.

Related errors

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