What causes "It looks like the config file at '{}' is not a valid JSON file." in huggingface/transformers?

Inspect the file at the path in the message (e.g. cat it) to confirm corruption

huggingface/transformers · error · OSError

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

Error message

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

What it means

OSError from GenerationConfig.from_pretrained(): the file at resolved_config_file was located, but _dict_from_json_file() failed with json.JSONDecodeError or UnicodeDecodeError, meaning the bytes are not parseable JSON. This points at a corrupted download, a truncated file, an HTML error page cached with a .json name, or a hand-edited file with syntax errors.

Source

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

            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}")

        if kwargs.get("_from_model_config", False):
            return cls.from_model_config(config_dict)
        elif kwargs.get("return_unused_kwargs") is True:
            config, unused_kwargs = cls.from_dict(config_dict, **kwargs)
            config._original_object_hash = hash(config)  # Hash to detect whether the instance was modified
            return config, unused_kwargs
        else:
            config = cls.from_dict(config_dict, **kwargs)
            config._original_object_hash = hash(config)  # Hash to detect whether the instance was modified
            return config

    @classmethod

View on GitHub (pinned to a597f97485)

Solutions

Inspect the file at the path in the message (e.g. cat it) to confirm corruption
Delete the cached file/directory and re-download: rm -rf ~/.cache/huggingface/hub/models--<org>--<name> or use huggingface-cli download --force
If you edited the file locally, validate it with python -m json.tool generation_config.json and fix syntax (double quotes, no trailing commas)
Check proxy/SSL interception if the content is HTML

Example fix

# before (truncated/invalid file)
cfg = GenerationConfig.from_pretrained('./my_model')  # OSError: not valid JSON
# after
# shell: rm ~/.cache/huggingface/hub/models--org--my_model
# or fix locally: python -m json.tool ./my_model/generation_config.json
cfg = GenerationConfig.from_pretrained('./my_model')

Defensive patterns

Strategy: validation

Validate before calling

import json, pathlib
p = pathlib.Path(local_dir) / 'generation_config.json'
if p.exists():
    json.loads(p.read_text())  # raises early with precise location if invalid

Try / catch

try:
    cfg = GenerationConfig.from_pretrained('./model')
except OSError as e:
    if 'not a valid JSON' in str(e):
        subprocess.run(['rm','-rf', cache_dir])  # purge and re-download
        cfg = GenerationConfig.from_pretrained('./model')
    else:
        raise

Prevention

Validate edited configs with python -m json.tool before use
Use huggingface-cli download for atomic downloads instead of interrupted manual fetches
Watch for proxy-injected HTML in cached files behind corporate networks

When it happens

Trigger: Interrupted download leaving a truncated generation_config.json in the HF cache; a proxy/portal returning HTML that got cached as the config; editing generation_config.json locally and leaving a trailing comma or single quotes; wrong-encoding file (UnicodeDecodeError).

Common situations: CI cache corruption; corporate proxies injecting login pages; manual config editing; disk-full during download.

Related errors

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