huggingface/transformers · error · ValueError

Some specified arguments are not used by the HfArgumentParse

Error message

Some specified arguments are not used by the HfArgumentParser: {remaining_args}

What it means

Error "Some specified arguments are not used by the HfArgumentParser: {remaining_args}" thrown in huggingface/transformers.

Source

Thrown at src/transformers/hf_argparser.py:354

            # args specified via the command line should overwrite args from files, so we add them last
            args = file_args + args if args is not None else file_args + sys.argv[1:]
        namespace, remaining_args = self.parse_known_args(args=args)
        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 vars(namespace).items() if k in keys}
            for k in keys:
                delattr(namespace, k)
            obj = dtype(**inputs)
            outputs.append(obj)
        if len(namespace.__dict__) > 0:
            # additional namespace.
            outputs.append(namespace)
        if return_remaining_strings:
            return (*outputs, remaining_args)
        else:
            if remaining_args:
                raise ValueError(f"Some specified arguments are not used by the HfArgumentParser: {remaining_args}")

            return (*outputs,)

    def parse_dict(self, args: dict[str, Any], allow_extra_keys: bool = False) -> tuple[DataClass, ...]:
        """
        Alternative helper method that does not use `argparse` at all, instead uses a dict and populating the dataclass
        types.

        Args:
            args (`dict`):
                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.

View on GitHub (pinned to a597f97485)

Solutions

1. Remove the unused CLI arguments or add matching fields to the dataclass.
2. Check for typos between CLI flags and dataclass field names.

When it happens

Trigger: Raised in HfArgumentParser.parse_args_into_dataclasses when unrecognized CLI arguments remain after parsing.

Common situations: Typos in command-line flags or passing arguments for a different script to a Trainer-based entrypoint.

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