huggingface/transformers · error · OSError

Can't load feature extractor for '{pretrained_model_name_or_

Error message

Can't load feature extractor 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 {feature_extractor_file} file

What it means

Raised after the config files were successfully located but neither the processor config nor the feature extractor file yielded a usable dict: the resolved processor file has no 'feature_extractor'/'audio_processor' key (legacy nested style absent) and no standalone feature extractor file was resolved. It means the checkpoint simply does not ship a feature extractor configuration.

Source

Thrown at src/transformers/feature_extraction_utils.py:529

                    " 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 {FEATURE_EXTRACTOR_NAME} file"
                )

        # Load feature_extractor 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
        feature_extractor_dict = None
        if resolved_processor_file is not None:
            processor_dict = safe_load_json_file(resolved_processor_file)
            if "feature_extractor" in processor_dict or "audio_processor" in processor_dict:
                feature_extractor_dict = processor_dict.get("feature_extractor", processor_dict.get("audio_processor"))

        if resolved_feature_extractor_file is not None and feature_extractor_dict is None:
            feature_extractor_dict = safe_load_json_file(resolved_feature_extractor_file)

        if feature_extractor_dict is None:
            raise OSError(
                f"Can't load feature extractor 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 {feature_extractor_file} file"
            )

        if is_local:
            logger.info(f"loading configuration file {resolved_feature_extractor_file}")
        else:
            logger.info(
                f"loading configuration file {feature_extractor_file} from cache at {resolved_feature_extractor_file}"
            )

        return feature_extractor_dict, kwargs

    @classmethod
    def from_dict(
        cls, feature_extractor_dict: dict[str, Any], **kwargs

View on GitHub (pinned to a597f97485)

Solutions

  1. Confirm the repo actually contains preprocessor_config.json or feature_extractor_config.json (check the Files tab on the Hub)
  2. Use the correct Auto class for the modality (AutoProcessor / AutoTokenizer / AutoImageProcessor) instead of AutoFeatureExtractor
  3. If the files exist locally, ensure they sit in the directory root (or pass subfolder=) so they get resolved
  4. Instantiate manually and save once: Wav2Vec2FeatureExtractor(...).save_pretrained(dir), then load from that directory

Example fix

# before
fe = AutoFeatureExtractor.from_pretrained("gpt2")  # no feature extractor shipped
# after
tok = AutoTokenizer.from_pretrained("gpt2")  # correct class for this checkpoint
Defensive patterns

Strategy: validation

Validate before calling

def has_feature_extractor_config(model_id: str) -> bool:
    import os, json
    if os.path.isdir(model_id):
        names = {"preprocessor_config.json", "feature_extractor_config.json"}
        if any(os.path.exists(os.path.join(model_id, n)) for n in names):
            return True
        p = os.path.join(model_id, "processor_config.json")
        if os.path.exists(p):
            return any(k in json.load(open(p)) for k in ("feature_extractor", "audio_processor"))
        return False
    return None  # needs a Hub check; see list_repo_files

Try / catch

try:
    fe = AutoFeatureExtractor.from_pretrained(model_id)
except OSError:
    fe = None  # fall back to a manually constructed extractor or different Auto class

Prevention

When it happens

Trigger: AutoFeatureExtractor.from_pretrained('<model>') where the repo has a processor_config.json without a nested 'feature_extractor'/'audio_processor' section and no preprocessor_config.json / feature_extractor_config.json at all; or a local directory missing those files.

Common situations: Loading a text-only or vision model through AutoFeatureExtractor, using a community upload that never included the preprocessor config, or pointing at a directory that contains only weights (pytorch_model.bin/safetensors) and config.json.

Related errors

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