sgl-project/sglang · error · RuntimeError

Failed to load image_processor for {model_path}: {e}. This m

Error message

Failed to load image_processor for {model_path}: {e}. This model requires an image processor for multimodal features. Check that the model files are complete and accessible.

What it means

The processor class declares an image_processor attribute, but AutoImageProcessor.from_pretrained failed with ImportError/OSError/ValueError, so the multimodal processor cannot be built. The underlying exception text is included.

Source

Thrown at python/sglang/srt/utils/hf_transformers/processor.py:180

        raise ValueError(f"Cannot determine processor class for {model_path}")

    proc_cls = get_class_from_dynamic_module(
        proc_ref, model_path, code_revision=revision
    )

    # Load sub-components individually (these succeed)
    tokenizer = AutoTokenizer.from_pretrained(
        model_path, trust_remote_code=trust_remote_code, revision=revision
    )
    init_kwargs = {"tokenizer": tokenizer}

    if "image_processor" in getattr(proc_cls, "attributes", []):
        try:
            init_kwargs["image_processor"] = AutoImageProcessor.from_pretrained(
                model_path, trust_remote_code=trust_remote_code, revision=revision
            )
        except (ImportError, OSError, ValueError) as e:
            raise RuntimeError(
                f"Failed to load image_processor for {model_path}: {e}. "
                f"This model requires an image processor for multimodal features. "
                f"Check that the model files are complete and accessible."
            ) from e

    # Instantiate feature extractor from its declared class
    fe_class_name = getattr(proc_cls, "feature_extractor_class", None)
    if fe_class_name:
        fe_class = getattr(transformers, fe_class_name, None)
        if fe_class is not None:
            try:
                init_kwargs["feature_extractor"] = fe_class()
            except TypeError as e:
                logger.warning(
                    "Cannot instantiate feature extractor %s with no arguments "
                    "for %s: %s",
                    fe_class_name,
                    model_path,

View on GitHub (pinned to 0132848349)

Solutions

  1. Read the chained {e} cause; fix that (e.g. pip install missing dep, upgrade transformers)
  2. Re-download the full model repo (check for missing preprocessor_config.json or image files)
  3. Fall back to a transformers/sglang version matching the model release
Defensive patterns

Strategy: try-catch

Validate before calling

try:
    from transformers import AutoImageProcessor; AutoImageProcessor.from_pretrained(model)
except Exception: fix deps/files before calling get_processor

Try / catch

try:
    get_processor(model)
except RuntimeError as e:
    if 'Failed to load image_processor' in str(e): inspect e.__cause__, then upgrade transformers / re-download

Prevention

When it happens

Trigger: Loading a VLM whose preprocessor_config.json exists but image processor files (e.g. preprocessor configs or required libs) are missing or incompatible with the installed transformers version.

Common situations: Incomplete model snapshots, transformers version mismatch for new VLMs, or missing optional image dependencies.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/4e2005bf809c4b34. Report an issue: GitHub.