{"record":{"id":"0a4fa259836fa5c6","repo":"huggingface/transformers","slug":"conversion-mapping-for-model-type-or-class-name","errorCode":null,"errorMessage":"Conversion mapping for '{model_type_or_class_name}' already exists. Pass overwrite=True to replace it.","messagePattern":"Conversion mapping for '(.+?)' already exists\\. Pass overwrite=True to replace it\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/conversion_mapping.py","lineNumber":1737,"sourceCode":"\ndef register_checkpoint_conversion_mapping(\n    model_type_or_class_name: str,\n    mapping: list[WeightConverter | WeightRenaming],\n    overwrite: bool = False,\n) -> None:\n    \"\"\"\n    Register a conversion mapping for a model type string or a class name.\n\n    Class names take priority over `model_type` strings during lookup (see\n    `extract_weight_conversions_for_model`), making it possible to define\n    task-head-specific or class-specific conversions that differ from the shared\n    `model_type` baseline.\n    \"\"\"\n    global _checkpoint_conversion_mapping_cache\n    if _checkpoint_conversion_mapping_cache is None:\n        _checkpoint_conversion_mapping_cache = _build_checkpoint_conversion_mapping()\n    if model_type_or_class_name in _checkpoint_conversion_mapping_cache and not overwrite:\n        raise ValueError(\n            f\"Conversion mapping for '{model_type_or_class_name}' already exists. Pass overwrite=True to replace it.\"\n        )\n    _checkpoint_conversion_mapping_cache[model_type_or_class_name] = mapping\n    # Keep track of what was added manually by the user\n    USER_REGISTERED_MAPPINGS.add(model_type_or_class_name)\n\n\ndef extract_weight_conversions_for_model(\n    model: PreTrainedModel,\n) -> list[WeightTransform] | None:\n    \"\"\"\n    Return the registered conversion list for `model`, or `None` if none exists.\n\n    Looks up by class name first (enables task-head-specific overrides), then\n    falls back to `model.config.model_type`.  Transforms are returned\n    unmodified; the caller sets `scope_prefix` on each transform for sub-module isolation.\n    \"\"\"\n    class_name = type(model).__name__","sourceCodeStart":1719,"sourceCodeEnd":1755,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/conversion_mapping.py#L1719-L1755","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass overwrite=True if you intentionally want to replace the existing mapping.","Register under a class name instead of the shared model_type key when you want a task-head-specific mapping without clobbering the baseline.","In notebooks, avoid re-running the registration cell or guard it with a membership check."],"exampleFix":"// before\nregister_weight_conversion(\"llama\", my_mapping)  # ValueError\n\n// after\nregister_weight_conversion(\"llama\", my_mapping, overwrite=True)","handlingStrategy":"try-catch","validationCode":"from transformers.conversion_mapping import _checkpoint_conversion_mapping_cache  # or public accessor\nif key in registry:\n    register_weight_conversion(key, mapping, overwrite=True)\nelse:\n    register_weight_conversion(key, mapping)","typeGuard":null,"tryCatchPattern":"try:\n    register_weight_conversion(name, mapping)\nexcept ValueError as e:\n    if \"already exists\" in str(e):\n        register_weight_conversion(name, mapping, overwrite=True)","preventionTips":["Register conversions idempotently: pass overwrite=True on re-registration or guard with a membership check.","Prefer class-name keys for specialized mappings to avoid colliding with built-in model_type keys."],"tags":["conversion-mapping","registration","checkpoint-conversion"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}