huggingface/transformers · error · ValueError

Some keys are not used by the HfArgumentParser: {sorted(unus

Error message

Some keys are not used by the HfArgumentParser: {sorted(unused_keys)}

What it means

Error "Some keys are not used by the HfArgumentParser: {sorted(unused_keys)}" thrown in huggingface/transformers.

Source

Thrown at src/transformers/hf_argparser.py:383

                dict containing config values
            allow_extra_keys (`bool`, *optional*, defaults to `False`):
                Defaults to False. If False, will raise an exception if the dict contains keys that are not parsed.

        Returns:
            Tuple consisting of:

                - the dataclass instances in the same order as they were passed to the initializer.
        """
        unused_keys = set(args.keys())
        outputs = []
        for dtype in self.dataclass_types:
            keys = {f.name for f in dataclasses.fields(dtype) if f.init}
            inputs = {k: v for k, v in args.items() if k in keys}
            unused_keys.difference_update(inputs.keys())
            obj = dtype(**inputs)
            outputs.append(obj)
        if not allow_extra_keys and unused_keys:
            raise ValueError(f"Some keys are not used by the HfArgumentParser: {sorted(unused_keys)}")
        return tuple(outputs)

    def parse_json_file(self, json_file: str | os.PathLike, allow_extra_keys: bool = False) -> tuple[DataClass, ...]:
        """
        Alternative helper method that does not use `argparse` at all, instead loading a json file and populating the
        dataclass types.

        Args:
            json_file (`str` or `os.PathLike`):
                File name of the json file to parse
            allow_extra_keys (`bool`, *optional*, defaults to `False`):
                Defaults to False. If False, will raise an exception if the json file contains keys that are not
                parsed.

        Returns:
            Tuple consisting of:

                - the dataclass instances in the same order as they were passed to the initializer.

View on GitHub (pinned to a597f97485)

Solutions

1. Remove unused keys from the JSON/dict, or add the corresponding dataclass fields.
2. Verify key spellings against the dataclass definition.

When it happens

Trigger: Raised in HfArgumentParser.parse_json_file/parse_dict when the provided keys do not match any dataclass field.

Common situations: Stale or misspelled keys in a training JSON config file that no longer correspond to dataclass fields.

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