huggingface/transformers · error · OSError

Can't load image processor for '{pretrained_model_name_or_pa

Error message

Can't load image processor for '{pretrained_model_name_or_path}'. If you were trying to load it from 'https://huggingface.co/models', make sure you don't have a local directory with the same name. Otherwise, make sure '{pretrained_model_name_or_path}' is the correct path to a directory containing a {image_processor_filename} file

What it means

Error "Can't load image processor for '{pretrained_model_name_or_path}'. If you were trying to load it from 'https://huggingface.co/models', make sure you don't have a local directory with the same name. Otherwise, make sure '{pretrained_model_name_or_path}' is the correct path to a directory containing a {image_processor_filename} file" thrown in huggingface/transformers.

Source

Thrown at src/transformers/image_processing_base.py:314

                    pretrained_model_name_or_path,
                    filename=image_processor_file,
                    cache_dir=cache_dir,
                    force_download=force_download,
                    proxies=proxies,
                    local_files_only=local_files_only,
                    token=token,
                    user_agent=user_agent,
                    revision=revision,
                    subfolder=subfolder,
                    _raise_exceptions_for_missing_entries=False,
                )
            except OSError:
                # Raise any environment error raise by `cached_file`. It will have a helpful error message adapted to
                # the original exception.
                raise
            except Exception:
                # For any other exception, we throw a generic error.
                raise OSError(
                    f"Can't load image processor for '{pretrained_model_name_or_path}'. If you were trying to load"
                    " it from 'https://huggingface.co/models', make sure you don't have a local directory with the"
                    f" same name. Otherwise, make sure '{pretrained_model_name_or_path}' is the correct path to a"
                    f" directory containing a {image_processor_filename} file"
                )

        # Load image_processor dict. Priority goes as (nested config if found -> image processor config)
        # We are downloading both configs because almost all models have a `processor_config.json` but
        # not all of these are nested. We need to check if it was saved recently as nested or if it is legacy style
        image_processor_dict = None
        if resolved_processor_file is not None:
            processor_dict = safe_load_json_file(resolved_processor_file)
            if "image_processor" in processor_dict:
                image_processor_dict = processor_dict["image_processor"]

        if resolved_image_processor_file is not None and image_processor_dict is None:
            image_processor_dict = safe_load_json_file(resolved_image_processor_file)

View on GitHub (pinned to a597f97485)

Solutions

1. Verify the path points to a directory containing a preprocessor_config.json file.
2. If loading from the Hub, pass the repo id and ensure no local directory shadows it.

When it happens

Trigger: Raised in ImageProcessingMixin.from_pretrained when no image processor config file can be resolved locally or from the Hub.

Common situations: Wrong repo id/path, a local directory shadowing a Hub model name, or a checkpoint missing preprocessor_config.json.

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/a0a2185fcb34aff7. Report an issue: GitHub.