huggingface/transformers · error · OSError

Can't load the configuration of '{pretrained_model_name_or_p

Error message

Can't load the configuration of '{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 {configuration_file} file

What it means

Generic OSError raised by PreTrainedConfig.from_pretrained / get_config_dict when any unexpected exception (not an OSError) occurs while resolving the config file for pretrained_model_name_or_path. It wraps failures such as HTTP errors, gated-repo access denials, or malformed repo ids into a single 'can't load the configuration' message pointing at the Hub and at local-directory shadowing.

Source

Thrown at src/transformers/configuration_utils.py:822

                    force_download=force_download,
                    proxies=proxies,
                    local_files_only=local_files_only,
                    token=token,
                    user_agent=user_agent,
                    revision=revision,
                    subfolder=subfolder,
                    _commit_hash=commit_hash,
                )
                if resolved_config_file is None:
                    return None, kwargs
                commit_hash = extract_commit_hash(resolved_config_file, commit_hash)
            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 the configuration of '{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"
                    f" name. Otherwise, make sure '{pretrained_model_name_or_path}' is the correct path to a directory"
                    f" containing a {configuration_file} file"
                )

        try:
            if gguf_file:
                config_dict = load_gguf_checkpoint(resolved_config_file, return_tensors=False)["config"]
            else:
                # Load config dict
                config_dict = cls._dict_from_json_file(resolved_config_file)

            config_dict["_commit_hash"] = commit_hash
        except (json.JSONDecodeError, UnicodeDecodeError):
            raise OSError(f"It looks like the config file at '{resolved_config_file}' is not a valid JSON file.")

        if is_local:

View on GitHub (pinned to a597f97485)

Solutions

1. Verify the model id spelling with huggingface-cli search or the Hub web UI.
2. If the repo is gated/private, run `huggingface-cli login` (or set HF_TOKEN) and request access.
3. If you have a local copy, pass its absolute path instead of the repo id, or rename the local directory that shadows the repo id.
4. For offline use, point HF_HUB_OFFLINE=1 at a populated cache or pass local_files_only=True.

Example fix

// before
config = AutoConfig.from_pretrained("meta-llama/Llama-3-8b")  # OSError: can't load

// after
from huggingface_hub import login
login()
config = AutoConfig.from_pretrained("meta-llama/Meta-Llama-3-8B")

from huggingface_hub import model_info
try:
    model_info("org/name", token=HF_TOKEN)  # raises clearly on typo/gating
except Exception as e:
    raise RuntimeError(f"Cannot access org/name on the Hub: {e}")

from transformers.utils import cached_file
try:
    AutoConfig.from_pretrained(name)
except OSError as e:
    if "Can't load the configuration" in str(e):
        # fall back to local snapshot or prompt for credentials
        config = AutoConfig.from_pretrained(local_path)

When it happens

Trigger: AutoConfig.from_pretrained("org/typo-name") with a typo; a gated/private repo without valid credentials; a request that fails with a non-OSError exception (e.g. requests.HTTPError); a local folder whose name matches the repo id so the Hub path is never used.

Common situations: Offline machines, expired Hugging Face tokens, gated models (Llama-style) not yet granted, corporate proxies rewriting responses, or a local directory named exactly like the model id.

Related errors

• It looks like the config file at '{resolved_config_file}' is
• No baseline with name '{name}' in {RESULTS_DIR}
• File not found: {audio}
• out_indices must be a list, got {type(self._out_indices)}
• out_indices must be valid indices for stage_names {self.stag

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