hiyouga/LlamaFactory · error · ValueError

Image processor was not found, please check and update your

Error message

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

What it means

Raised when the plugin supports images (image_token is not None) and a processor object exists, but getattr(processor, 'image_processor', None) is None — the processor lacks an image_processor sub-processor. This means the model's processor files exist but are not a vision processor (or are an outdated variant), so image preprocessing cannot proceed.

Source

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

            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."""
        num_image_tokens, num_video_tokens, num_audio_tokens = 0, 0, 0
        for message in messages:
            num_image_tokens += message["content"].count(IMAGE_PLACEHOLDER)

View on GitHub (pinned to f28afaf635)

Solutions

Restore/complete the model's original processor files (preprocessor_config.json, processor_config.json) from the upstream checkpoint.
Upgrade transformers (and LlamaFactory) to versions that support the model's processor class.
Verify AutoProcessor.from_pretrained(model_path) returns an object with .image_processor in a quick REPL before training.
If the model is genuinely text-only, choose a text-only template.

Example fix

# before: /models/myvlm contains tokenizer files only

# after: ensure the repo snapshot includes
# /models/myvlm/preprocessor_config.json  (from the original VLM checkpoint)
# verify:
from transformers import AutoProcessor
p = AutoProcessor.from_pretrained("/models/myvlm", trust_remote_code=True)
assert getattr(p, "image_processor", None) is not None

Defensive patterns

Strategy: validation

Validate before calling

from transformers import AutoProcessor

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

Prevention

Diff your local model dir against the upstream repo file list before training.
Pin transformers >= the model card's stated minimum.
Never hand-copy tokenizer files into a VLM directory.

When it happens

Trigger: A checkpoint whose processor config belongs to a text tokenizer or feature extractor without an image_processor attribute; mixing processor files from different model families; older transformers versions where the processor class for the model does not expose image_processor.

Common situations: Manually copying tokenizer files into a VLM directory; using a custom/quantized re-upload that dropped preprocessor_config.json so AutoProcessor falls back to the tokenizer; transformers version older than the model's support.

Related errors

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