{"record":{"id":"fd03f7b67b55b120","repo":"mlflow/mlflow","slug":"couldn-t-find-a-loader-class-for-class-name","errorCode":null,"errorMessage":"Couldn't find a loader class for {class_name}","messagePattern":"Couldn't find a loader class for (.+?)","errorType":"exception","errorClass":"MlflowException","httpStatus":null,"severity":"error","filePath":"mlflow/transformers/model_io.py","lineNumber":290,"sourceCode":"\n    # if the class is available in transformers natively,\n    # then we don't need to execute any custom code.\n    if hasattr(transformers, class_name):\n        cls = getattr(transformers, class_name)\n        return cls, False\n    else:\n        # else, we need to fetch the correct AutoClass.\n        # this is defined in the `auto_map` field. there\n        # should only be one AutoClass that maps to the\n        # model's class name.\n        auto_classes = [\n            auto_class\n            for auto_class, module in config.auto_map.items()\n            if module.split(\".\")[-1] == class_name\n        ]\n\n        if len(auto_classes) == 0:\n            raise MlflowException(f\"Couldn't find a loader class for {class_name}\")\n\n        auto_class = auto_classes[0]\n        cls = getattr(transformers, auto_class)\n\n        # we will need to trust remote code when loading the model\n        return cls, True\n\n\ndef _load_model(model_name_or_path, flavor_conf, accelerate_conf, device, revision=None):\n    \"\"\"\n    Try to load a model with various loading strategies.\n      1. Try to load the model with accelerate\n      2. Try to load the model with the specified device\n      3. Load the model without the device\n    \"\"\"\n    import transformers\n\n    if hasattr(transformers, flavor_conf[FlavorKey.MODEL_TYPE]):","sourceCodeStart":272,"sourceCodeEnd":308,"githubUrl":"https://github.com/mlflow/mlflow/blob/6a27f2decc0b76eb1b54af31849784addb357dbc/mlflow/transformers/model_io.py#L272-L308","documentation":"MLflow's transformers flavor supports loading custom models defined via a config's auto_map. When building the loader, _load_class_from_transformers_config scans config.auto_map for an entry whose module path ends with the requested class name; if none matches, it cannot resolve a loader class and raises this MlflowException.","triggerScenarios":"Loading (mlflow.transformers.load_model or pyfunc load) a custom transformers model whose config.json auto_map does not contain a key mapping to a module ending with the expected class name (e.g. AutoModelForSeq2SeqLM missing), or the auto_map entries point at different class names than the saved model.","commonSituations":"Custom 'trust_remote_code' repos where the author renamed classes or only registered some of the auto_map entries; hand-edited or incomplete config.json; loading a model saved with a different transformers architecture than expected.","solutions":["Open the model's config.json and ensure auto_map includes an entry whose module path ends with the class name being loaded (e.g. 'AutoModelForSeq2SeqLM': 'modeling.CustomModel').","Add the missing auto_map entry and re-save/re-upload the model.","Load the model directly with transformers (AutoModel.from_pretrained(..., trust_remote_code=True)) to verify the config is valid before going through MLflow.","Ensure you are loading the intended revision/commit of the repo — an older revision may lack the auto_map entry."],"exampleFix":"// before (config.json)\n{\"auto_map\": {\"AutoModel\": \"modeling_chat.CustomChatModel\"}}\n// after\n{\"auto_map\": {\"AutoModel\": \"modeling_chat.CustomChatModel\", \"AutoModelForCausalLM\": \"modeling_chat.CustomChatModel\"}}","handlingStrategy":"validation","validationCode":"import json\nwith open(f'{model_dir}/config.json') as f:\n    cfg = json.load(f)\nassert any(k.endswith(class_name) or v.split('.')[-1] == class_name for k, v in cfg.get('auto_map', {}).items()), f\"auto_map lacks entry for {class_name}\"","typeGuard":"def has_auto_map_entry(config, class_name: str) -> bool:\n    am = getattr(config, 'auto_map', None) or {}\n    return any(module.split('.')[-1] == class_name for module in am.values())","tryCatchPattern":"try:\n    model = mlflow.transformers.load_model(uri)\nexcept MlflowException as e:\n    if \"Couldn't find a loader class\" in str(e):\n        model = AutoModel.from_pretrained(path, trust_remote_code=True)\n    else:\n        raise","preventionTips":["Inspect auto_map in config.json before logging custom transformers models","Register all relevant Auto* classes in auto_map when saving trust_remote_code models","Test mlflow.transformers.load_model round-trip right after save_model"],"tags":["transformers","huggingface","model-loading","config"],"backgroundTag":"missing-autoload-mapping","analyzedSha":"6a27f2decc0b76eb1b54af31849784addb357dbc","analyzedAt":"2026-08-29T20:54:51.419Z","schemaVersion":2},"datasetVersion":"2026-08-29T22:17:34.462Z"}