huggingface/transformers · error · OSError

It looks like the config file at '{resolved_config_file}' is

Error message

It looks like the config file at '{resolved_config_file}' is not a valid JSON file.

What it means

OSError raised by from_pretrained when the resolved config file (config.json or gguf) cannot be parsed because it raises json.JSONDecodeError or UnicodeDecodeError. The file was found but its bytes are not valid JSON/text, so _dict_from_json_file fails.

Source

Thrown at src/transformers/configuration_utils.py:838

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

        # timm models are not saved with the model_type in the config file
        if "model_type" not in config_dict and is_timm_config_dict(config_dict):
            config_dict["model_type"] = "timm_wrapper"

        # Some checkpoints may contain the wrong model_type in the config file.
        # Allow the user to override it but warn them that it might not work.
        if "model_type" in kwargs and config_dict["model_type"] != kwargs["model_type"]:
            logger.warning(
                f"{configuration_file} has 'model_type={config_dict['model_type']}' but you overrode "
                f"it with 'model_type={kwargs['model_type']}'. This may lead to unexpected behavior."
            )
            config_dict["model_type"] = kwargs["model_type"]

View on GitHub (pinned to a597f97485)

Solutions

Open the resolved_config_file path from the message in an editor or `python -m json.tool` and fix the JSON syntax.
If the file came from the hub cache, delete that cache entry (or run `huggingface-cli download --force`) so it is re-downloaded cleanly.
Verify encoding: re-save the file as UTF-8 without BOM.

Example fix

// before
{"model_type": "gpt2", "n_embd": 768,}  # trailing comma -> OSError

// after
{"model_type": "gpt2", "n_embd": 768}

Defensive patterns

Strategy: validation

Validate before calling

import json, pathlib
p = pathlib.Path(config_path)
try:
    json.loads(p.read_text(encoding="utf-8"))
except (json.JSONDecodeError, UnicodeDecodeError) as e:
    raise ValueError(f"config {p} is corrupt: {e}")  # re-download or fix before from_pretrained

Try / catch

try:
    AutoConfig.from_pretrained(path)
except OSError as e:
    if "not a valid JSON file" in str(e):
        clear_cache_for(path)
        AutoConfig.from_pretrained(path)  # re-download once

Prevention

Validate JSON with python -m json.tool after hand-editing config files.
Use huggingface-cli download for atomic downloads instead of interrupted direct fetches.

When it happens

Trigger: A truncated download (interrupted hub download leaving a partial file in the cache), a hand-edited config.json with a stray comma or trailing text, a config.json saved with a non-UTF-8 encoding, or a GGUF file that is not actually GGUF.

Common situations: Corrupted HF cache after a killed process; config.json edited via shell echo/heredoc introducing bad quotes; files synced through tools that mangled encoding; partial uploads to a repo.

Related errors

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