{"record":{"id":"036db2bf964c3bca","repo":"hiyouga/LlamaFactory","slug":"hfmodel-instance-is-required-for-cls-name","errorCode":null,"errorMessage":"HFModel instance is required for {cls.__name__}.","messagePattern":"HFModel instance is required for (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/llamafactory/v1/plugins/model_plugins/kernels/base.py","lineNumber":45,"sourceCode":"\n    def __init_subclass__(cls, **kwargs) -> None:\n        super().__init_subclass__(**kwargs)\n        ensure_methods_implemented(cls)\n\n    @staticmethod\n    @abstractmethod\n    def check_device() -> None: ...\n\n    @staticmethod\n    def check_deps() -> None:\n        pass\n\n    @classmethod\n    def apply(cls, **kwargs) -> HFModel:\n        cls.check_device()\n        cls.check_deps()\n        if kwargs.get(\"model\") is None:\n            raise ValueError(f\"HFModel instance is required for {cls.__name__}.\")\n\n        return cls._apply(**kwargs)\n\n    @staticmethod\n    @abstractmethod\n    def _apply(**kwargs) -> HFModel: ...\n","sourceCodeStart":27,"sourceCodeEnd":52,"githubUrl":"https://github.com/hiyouga/LlamaFactory/blob/f28afaf6355af515454dfb16c97d728307c93897/src/llamafactory/v1/plugins/model_plugins/kernels/base.py#L27-L52","documentation":"BaseKernel.apply() runs device/dependency checks then requires a 'model' key in kwargs; passing model=None (or omitting it) raises this ValueError naming the kernel class. It guards against applying a patch kernel when no HF model instance was loaded/created yet.","triggerScenarios":"Calling KernelPlugin('liger_kernel').apply(model=None, ...) or invoking apply_kernels before the model loader returned a model (model still None during a failed load that was swallowed).","commonSituations":"Custom model-loading pipelines that apply kernels before load completes; a load function returning None on quantization failure and the error surfacing later as this; glue code that forwards a possibly-None variable.","solutions":["Ensure the HF model is loaded (and not None) before apply; check the load call's return value.","If the model load failed, fix the root cause upstream (path, quantization config, memory).","Pass the model explicitly: KernelPlugin(name).apply(model=model, ...).","Add an assert model is not None after loading to fail fast with context."],"exampleFix":"# before\nmodel = load_model(cfg)  # returned None on failure\napply_kernels(model, kernel_config)\n\n# after\nmodel = load_model(cfg)\nassert model is not None, \"model load failed\"\napply_kernels(model, kernel_config)","handlingStrategy":"type-guard","validationCode":"from transformers import PreTrainedModel\nassert isinstance(model, PreTrainedModel) and model is not None, 'load a real HF model before applying kernels'","typeGuard":"def is_hf_model(m) -> bool:\n    \"\"\"True when m is a loaded HF PreTrainedModel.\"\"\"\n    from transformers import PreTrainedModel\n    return isinstance(m, PreTrainedModel)","tryCatchPattern":"try:\n    model = apply_kernels(model, kernel_config)\nexcept ValueError as e:\n    if 'HFModel instance is required' in str(e):\n        raise SystemExit('model load failed upstream; fix loader') from None\n    raise","preventionTips":["Assert model is not None immediately after loading.","Apply kernels only in the load pipeline right after a successful load.","Never swallow model-loader exceptions before the kernel step."],"tags":["kernels","model-loading","validation"],"backgroundTag":null,"analyzedSha":"f28afaf6355af515454dfb16c97d728307c93897","analyzedAt":"2026-08-14T21:57:28.298Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}