hiyouga/LlamaFactory · error · ValueError

HFModel instance is required for {cls.__name__}.

Error message

HFModel instance is required for {cls.__name__}.

What it means

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.

Source

Thrown at src/llamafactory/v1/plugins/model_plugins/kernels/base.py:45

    def __init_subclass__(cls, **kwargs) -> None:
        super().__init_subclass__(**kwargs)
        ensure_methods_implemented(cls)

    @staticmethod
    @abstractmethod
    def check_device() -> None: ...

    @staticmethod
    def check_deps() -> None:
        pass

    @classmethod
    def apply(cls, **kwargs) -> HFModel:
        cls.check_device()
        cls.check_deps()
        if kwargs.get("model") is None:
            raise ValueError(f"HFModel instance is required for {cls.__name__}.")

        return cls._apply(**kwargs)

    @staticmethod
    @abstractmethod
    def _apply(**kwargs) -> HFModel: ...

View on GitHub (pinned to f28afaf635)

Solutions

1. Ensure the HF model is loaded (and not None) before apply; check the load call's return value.
2. If the model load failed, fix the root cause upstream (path, quantization config, memory).
3. Pass the model explicitly: KernelPlugin(name).apply(model=model, ...).
4. Add an assert model is not None after loading to fail fast with context.

Example fix

# before
model = load_model(cfg)  # returned None on failure
apply_kernels(model, kernel_config)

# after
model = load_model(cfg)
assert model is not None, "model load failed"
apply_kernels(model, kernel_config)

from transformers import PreTrainedModel
assert isinstance(model, PreTrainedModel) and model is not None, 'load a real HF model before applying kernels'

def is_hf_model(m) -> bool:
    """True when m is a loaded HF PreTrainedModel."""
    from transformers import PreTrainedModel
    return isinstance(m, PreTrainedModel)

try:
    model = apply_kernels(model, kernel_config)
except ValueError as e:
    if 'HFModel instance is required' in str(e):
        raise SystemExit('model load failed upstream; fix loader') from None
    raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• kernel_config.name must be a string.
• kernel_config.name must contain at least one kernel name.
• Unknown Liger op(s) {sorted(ops)} for model_type={model_type
• Invalid input type {input_item.type}.
• Invalid tools

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/036db2bf964c3bca. Report an issue: GitHub.