huggingface/transformers · error · AssertionError

Provided path ({save_directory}) should be a directory, not

Error message

Provided path ({save_directory}) should be a directory, not a file

What it means

Error "Provided path ({save_directory}) should be a directory, not a file" thrown in huggingface/transformers.

Source

Thrown at src/transformers/image_processing_base.py:199

        return cls.from_dict(image_processor_dict, **kwargs)

    def save_pretrained(self, save_directory: str | os.PathLike, push_to_hub: bool = False, **kwargs):
        """
        Save an image processor object to the directory `save_directory`, so that it can be re-loaded using the
        [`~image_processing_utils.ImageProcessingMixin.from_pretrained`] class method.

        Args:
            save_directory (`str` or `os.PathLike`):
                Directory where the image processor JSON file will be saved (will be created if it does not exist).
            push_to_hub (`bool`, *optional*, defaults to `False`):
                Whether or not to push your model to the Hugging Face model hub after saving it. You can specify the
                repository you want to push to with `repo_id` (will default to the name of `save_directory` in your
                namespace).
            kwargs (`dict[str, Any]`, *optional*):
                Additional key word arguments passed along to the [`~utils.PushToHubMixin.push_to_hub`] method.
        """
        if os.path.isfile(save_directory):
            raise AssertionError(f"Provided path ({save_directory}) should be a directory, not a file")

        os.makedirs(save_directory, exist_ok=True)

        if push_to_hub:
            commit_message = kwargs.pop("commit_message", None)
            repo_id = kwargs.pop("repo_id", save_directory.split(os.path.sep)[-1])
            repo_id = hf_api().create_repo(repo_id, exist_ok=True, **kwargs).repo_id
            files_timestamps = self._get_files_timestamps(save_directory)

        # If we have a custom config, we copy the file defining it in the folder and set the attributes so it can be
        # loaded from the Hub.
        if self._auto_class is not None:
            custom_object_save(self, save_directory, config=self)

        # If we save using the predefined names, we can load using `from_pretrained`
        output_image_processor_file = os.path.join(save_directory, IMAGE_PROCESSOR_NAME)

        self.to_json_file(output_image_processor_file)

View on GitHub (pinned to a597f97485)

Solutions

1. Pass a directory path to `save_pretrained`, not a file path.
2. Create the directory first with `os.makedirs(save_directory, exist_ok=True)`.

When it happens

Trigger: Raised in ImageProcessingMixin.save_pretrained when save_directory points to an existing file instead of a directory.

Common situations: Passing a file path (e.g. .../preprocessor_config.json) instead of its parent directory to save_pretrained.

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