hiyouga/LlamaFactory · error · ValueError

Processor was not found, please check and update your model

Error message

Processor was not found, please check and update your model file.

What it means

ValueError from BasePlugin._validate_inputs: the template's plugin expects image input (image_token is not None) but `processor` passed to the data pipeline is None — no ProcessorMixin was found for the model. LlamaFactory locates the processor via AutoProcessor/processor files in the model repo; absence means the model files are incomplete or the wrong checkpoint is used.

Source

Thrown at src/llamafactory/data/mm_plugin.py:178

            processor, "audio_processor", None
        )
        if len(images) != 0 and self.image_token is None:
            raise ValueError(
                "This model does not support image input. Please check whether the correct `template` is used."
            )

        if len(videos) != 0 and self.video_token is None:
            raise ValueError(
                "This model does not support video input. Please check whether the correct `template` is used."
            )

        if len(audios) != 0 and self.audio_token is None:
            raise ValueError(
                "This model does not support audio input. Please check whether the correct `template` is used."
            )

        if self.image_token is not None and processor is None:
            raise ValueError("Processor was not found, please check and update your model file.")

        if self.image_token is not None and image_processor is None:
            raise ValueError("Image processor was not found, please check and update your model file.")

        if self.video_token is not None and video_processor is None:
            raise ValueError("Video processor was not found, please check and update your model file.")

        if self.audio_token is not None and feature_extractor is None:
            raise ValueError("Audio feature extractor was not found, please check and update your model file.")

    def _validate_messages(
        self,
        messages: list[dict[str, str]],
        images: list["ImageInput"],
        videos: list["VideoInput"],
        audios: list["AudioInput"],
    ):
        r"""Validate if the number of images, videos and audios match the number of placeholders in messages."""

View on GitHub (pinned to f28afaf635)

Solutions

Point model_name_or_path at the complete multimodal checkpoint that includes processor files (preprocessor_config.json etc.).
Re-download the model to repair missing files (delete and refetch the snapshot, or use hf download).
If combining an adapter with a base model, keep the multimodal base in model_name_or_path and pass the adapter via adapter_name_or_path.
If the run is text-only, switch template to a text-only one so no processor is required.

Example fix

# before
model_name_or_path: /models/qwen2vl-lora-adapter  # adapter dir lacks processor
template: qwen2vl

# after
model_name_or_path: Qwen/Qwen2-VL-7B-Instruct
adapter_name_or_path: /models/qwen2vl-lora-adapter
template: qwen2vl

Defensive patterns

Strategy: validation

Validate before calling

from transformers import AutoProcessor

def model_has_processor(model_path: str) -> bool:
    try:
        return AutoProcessor.from_pretrained(model_path, trust_remote_code=True) is not None
    except Exception:
        return False

Prevention

Run get_template_and_fix_tokenizer/AutoProcessor in a dry-run script before launching long jobs.
Keep full multimodal checkpoints intact; pass adapters via adapter_name_or_path.
Verify downloads completed (snapshot file counts) after network errors.

When it happens

Trigger: Loading a vision-language template with a model path that lacks preprocessor_config.json/processor files (e.g. only the LM backbone was uploaded, or a LoRA adapter directory is used as model_name_or_path); checkpoint downloads interrupted so processor files are missing.

Common situations: Users pointing model_name_or_path at a text-only base model while the template is multimodal; manually pruned repos; adapters saved without the base processor; partial downloads from hf_hub.

Related errors

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