huggingface/transformers · error · ValueError

Conversion mapping for '{model_type_or_class_name}' already

Error message

Conversion mapping for '{model_type_or_class_name}' already exists. Pass overwrite=True to replace it.

What it means

ValueError from conversion_mapping.register_weight_conversion: a mapping is already registered under this key (a model_type string or class name) and the call did not pass overwrite=True. The registry is global, so duplicate registrations are treated as probable bugs rather than silently replacing existing behavior.

Source

Thrown at src/transformers/conversion_mapping.py:1737

def register_checkpoint_conversion_mapping(
    model_type_or_class_name: str,
    mapping: list[WeightConverter | WeightRenaming],
    overwrite: bool = False,
) -> None:
    """
    Register a conversion mapping for a model type string or a class name.

    Class names take priority over `model_type` strings during lookup (see
    `extract_weight_conversions_for_model`), making it possible to define
    task-head-specific or class-specific conversions that differ from the shared
    `model_type` baseline.
    """
    global _checkpoint_conversion_mapping_cache
    if _checkpoint_conversion_mapping_cache is None:
        _checkpoint_conversion_mapping_cache = _build_checkpoint_conversion_mapping()
    if model_type_or_class_name in _checkpoint_conversion_mapping_cache and not overwrite:
        raise ValueError(
            f"Conversion mapping for '{model_type_or_class_name}' already exists. Pass overwrite=True to replace it."
        )
    _checkpoint_conversion_mapping_cache[model_type_or_class_name] = mapping
    # Keep track of what was added manually by the user
    USER_REGISTERED_MAPPINGS.add(model_type_or_class_name)


def extract_weight_conversions_for_model(
    model: PreTrainedModel,
) -> list[WeightTransform] | None:
    """
    Return the registered conversion list for `model`, or `None` if none exists.

    Looks up by class name first (enables task-head-specific overrides), then
    falls back to `model.config.model_type`.  Transforms are returned
    unmodified; the caller sets `scope_prefix` on each transform for sub-module isolation.
    """
    class_name = type(model).__name__

View on GitHub (pinned to a597f97485)

Solutions

1. Pass overwrite=True if you intentionally want to replace the existing mapping.
2. Register under a class name instead of the shared model_type key when you want a task-head-specific mapping without clobbering the baseline.
3. In notebooks, avoid re-running the registration cell or guard it with a membership check.

Example fix

// before
register_weight_conversion("llama", my_mapping)  # ValueError

// after
register_weight_conversion("llama", my_mapping, overwrite=True)

from transformers.conversion_mapping import _checkpoint_conversion_mapping_cache  # or public accessor
if key in registry:
    register_weight_conversion(key, mapping, overwrite=True)
else:
    register_weight_conversion(key, mapping)

try:
    register_weight_conversion(name, mapping)
except ValueError as e:
    if "already exists" in str(e):
        register_weight_conversion(name, mapping, overwrite=True)

When it happens

Trigger: Calling register_weight_conversion("llama", [...]) when the built-in llama mapping is already cached; re-running a notebook cell that registers a custom mapping for the same class name twice.

Common situations: Interactive/notebook re-execution; libraries that register conversions at import time being imported twice under different names; trying to override a built-in model_type mapping without realizing overwrite is required.

Related errors

• {auto_class} is not a valid auto class.

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