huggingface/transformers · error · RuntimeError

Type resolution failed for {dtype}. Try declaring the class

Error message

Type resolution failed for {dtype}. Try declaring the class in global scope or removing line of `from __future__ import annotations` which opts in Postponed Evaluation of Annotations (PEP 563)

What it means

Error "Type resolution failed for {dtype}. Try declaring the class in global scope or removing line of `from __future__ import annotations` which opts in Postponed Evaluation of Annotations (PEP 563)" thrown in huggingface/transformers.

Source

Thrown at src/transformers/hf_argparser.py:260

            bool_kwargs["default"] = False
            parser.add_argument(
                f"--no_{field.name}",
                f"--no-{field.name.replace('_', '-')}",
                action="store_false",
                dest=field.name,
                **bool_kwargs,
            )

    def _add_dataclass_arguments(self, dtype: DataClassType):
        if hasattr(dtype, "_argument_group_name"):
            parser = self.add_argument_group(dtype._argument_group_name)
        else:
            parser = self

        try:
            type_hints: dict[str, type] = get_type_hints(dtype)
        except NameError:
            raise RuntimeError(
                f"Type resolution failed for {dtype}. Try declaring the class in global scope or "
                "removing line of `from __future__ import annotations` which opts in Postponed "
                "Evaluation of Annotations (PEP 563)"
            )

        for field in dataclasses.fields(dtype):
            if not field.init:
                continue
            field.type = type_hints[field.name]
            self._parse_dataclass_field(parser, field)

    def parse_args_into_dataclasses(
        self,
        args=None,
        return_remaining_strings=False,
        look_for_args_file=True,
        args_filename=None,
        args_file_flag=None,

View on GitHub (pinned to a597f97485)

Solutions

1. Remove `from __future__ import annotations` from the file defining the dataclass.
2. Define the type at module global scope so it can be resolved.

When it happens

Trigger: Raised in HfArgumentParser when get_type_hints fails to resolve a field's annotation.

Common situations: Dataclass declared in a local scope or with 'from __future__ import annotations' referencing names unavailable at parse time.

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