huggingface/transformers · error · OSError

Can't load the configuration of '{}'. If you were trying to

Error message

Can't load the configuration of '{}'. 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 '{}' is the correct path to a directory containing a {} file

What it means

OSError from GenerationConfig.from_pretrained(): resolving the config file via cached_file() failed with an exception other than OSError (network errors already re-raise with better messages), so a generic 'cannot load configuration' error is thrown. It hints at the two classic causes: a local directory shadowing the Hub repo name, or a wrong repo/path that lacks the config file (by default generation_config.json).

Source

Thrown at src/transformers/generation/configuration_utils.py:1067

                    configuration_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,
                    _commit_hash=commit_hash,
                )
                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}'. 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}' is the correct path to a directory"
                    f" containing a {configuration_file} file"
                )

        try:
            # 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:
            logger.info(f"loading configuration file {resolved_config_file}")
        else:
            logger.info(f"loading configuration file {configuration_file} from cache at {resolved_config_file}")

View on GitHub (pinned to a597f97485)

Solutions

Verify the repo id/path exists and contains generation_config.json (check on the Hub or with huggingface_hub.list_repo_files)
If a local directory shares the model name, rename it or run from a different cwd / pass the full local path to the directory
For private models, authenticate: huggingface-cli login (HF_TOKEN) and confirm access
Check connectivity/proxy settings (HTTPS_PROXY) and retry — transient Hub failures can trigger this path

Example fix

# before
cfg = GenerationConfig.from_pretrained('mistral/Mistral-7B')  # typo
# after
from huggingface_hub import list_repo_files
print(list_repo_files('mistralai/Mistral-7B-v0.1'))
cfg = GenerationConfig.from_pretrained('mistralai/Mistral-7B-v0.1')

Defensive patterns

Strategy: retry

Validate before calling

from huggingface_hub import model_info
try:
    model_info(repo_id)  # raises if repo missing/inaccessible
except Exception:
    print('repo unavailable; check name, credentials, network')

Try / catch

for attempt in range(3):
    try:
        cfg = GenerationConfig.from_pretrained(repo_id)
        break
    except OSError as e:
        if attempt == 2 or 'not a valid JSON' in str(e):
            raise
        time.sleep(2 ** attempt)  # transient Hub errors

Prevention

Pin exact repo revisions in production (revision='commit-or-tag')
Pre-download configs with huggingface-cli download and run offline from local paths
Avoid local directories with the same name as Hub repos in your working directory

When it happens

Trigger: GenerationConfig.from_pretrained('org/nonexistent-repo'); a local folder named like the Hub model id in the working directory intercepting resolution; a repo without generation_config.json; private/gated repo without credentials (non-OSError path); offline env var conflicts.

Common situations: Typos in repo ids; running scripts from a directory that contains a folder named after the model; rate limiting or transient Hub errors that surface as generic exceptions; new local models missing generation_config.json.

Related errors

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