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_NAME} file

What it means

Thrown by FeatureExtractionMixin.from_pretrained when fetching the feature extractor config from the Hub or local path fails with a non-OSError exception (OSError from cached_file is re-raised as-is with its own message). It is a generic wrapper indicating the config download/resolution step exploded unexpectedly. The message also hints at the classic failure where a local directory shadows a Hub model id.

Source

Thrown at src/transformers/feature_extraction_utils.py:509

                    pretrained_model_name_or_path,
                    filename=feature_extractor_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 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_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)

View on GitHub (pinned to a597f97485)

Solutions

Inspect the chained exception (__cause__/__context__) to see the real underlying error before this generic wrapper
Verify the model id exists on https://huggingface.co/models and hosts a feature extractor file (preprocessor_config.json or feature_extractor_config.json)
Rename or move any local directory whose name equals the model id so it cannot shadow the Hub repo
Check connectivity/proxy settings (HTTPS_PROXY, HF_ENDPOINT) or enable HF_HUB_OFFLINE=1 when working purely from cache
Pass revision= or subfolder= explicitly if the file lives outside the default branch/root

Example fix

// before
fe = Wav2Vec2FeatureExtractor.from_pretrained("facebook/wav2vec2-base-960h-typo")
// after (from a local directory that contains preprocessor_config.json)
fe = Wav2Vec2FeatureExtractor.from_pretrained("./models/wav2vec2-base-960h")

Defensive patterns

Strategy: try-catch

Validate before calling

from huggingface_hub import list_repo_files
import os

def feature_extractor_files_available(model_id: str, token=None) -> bool:
    if os.path.isdir(model_id):
        return any(f in os.listdir(model_id) for f in ("preprocessor_config.json", "feature_extractor_config.json"))
    try:
        files = list_repo_files(model_id, token=token)
    except Exception:
        return False
    return any(f in files for f in ("preprocessor_config.json", "feature_extractor_config.json", "processor_config.json"))

Try / catch

from transformers import AutoFeatureExtractor
try:
    fe = AutoFeatureExtractor.from_pretrained(model_id)
except OSError as e:
    # chained exception carries the root cause
    logging.error("feature extractor load failed: %s", e)
    raise

Prevention

Avoid naming local directories the same as Hub model ids you intend to load
Pin revision= for reproducible loads
Pre-download configs with huggingface-cli and set HF_HUB_OFFLINE=1 in air-gapped environments

When it happens

Trigger: Calling FeatureExtractor.from_pretrained / AutoFeatureExtractor.from_pretrained where get_cached_file raises something other than OSError: HTTP errors not mapped to OSError, malformed proxies, an invalid revision/subfolder, or a local directory named identically to a Hub model that lacks a feature extractor file.

Common situations: Offline machine without HF_HUB_OFFLINE set, typo'd model id, corporate proxy intercepting huggingface.co, a local folder (e.g. './wav2vec2-base') shadowing the repo id, or requesting a revision/subfolder that does not contain preprocessor_config.json.

Related errors

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