huggingface/transformers · error · RuntimeError

Unresolved type detected, which should have been done with t

Error message

Unresolved type detected, which should have been done with the help of `typing.get_type_hints` method by default

What it means

Error "Unresolved type detected, which should have been done with the help of `typing.get_type_hints` method by default" thrown in huggingface/transformers.

Source

Thrown at src/transformers/hf_argparser.py:159

        self.dataclass_types = list(dataclass_types)
        for dtype in self.dataclass_types:
            self._add_dataclass_arguments(dtype)

    @staticmethod
    def _parse_dataclass_field(parser: ArgumentParser, field: dataclasses.Field):
        # Long-option strings are conventionlly separated by hyphens rather
        # than underscores, e.g., "--long-format" rather than "--long_format".
        # Argparse converts hyphens to underscores so that the destination
        # string is a valid attribute name. Hf_argparser should do the same.
        long_options = [f"--{field.name}"]
        if "_" in field.name:
            long_options.append(f"--{field.name.replace('_', '-')}")

        kwargs = field.metadata.copy()
        # field.metadata is not used at all by Data Classes,
        # it is provided as a third-party extension mechanism.
        if isinstance(field.type, str):
            raise RuntimeError(
                "Unresolved type detected, which should have been done with the help of "
                "`typing.get_type_hints` method by default"
            )

        aliases = kwargs.pop("aliases", [])
        if isinstance(aliases, str):
            aliases = [aliases]

        origin_type = getattr(field.type, "__origin__", field.type)
        if origin_type is Union or (hasattr(types, "UnionType") and isinstance(origin_type, types.UnionType)):
            if str not in field.type.__args__ and (
                len(field.type.__args__) != 2 or type(None) not in field.type.__args__
            ):
                raise ValueError(
                    "Only `Union[X, NoneType]` (i.e., `Optional[X]`) is allowed for `Union` because"
                    " the argument parser only supports one type per argument."
                    f" Problem encountered in field '{field.name}'."
                )

View on GitHub (pinned to a597f97485)

Solutions

1. Avoid unresolved/forward-reference types in the dataclass; use concrete types.
2. Call `typing.get_type_hints` or move the referenced type into scope.

When it happens

Trigger: Raised in HfArgumentParser when a dataclass field type remains an unresolved string/ForwardRef after get_type_hints.

Common situations: Dataclass fields annotated with types not importable at parse time or left as strings under postponed annotation evaluation.

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