{"record":{"id":"e5316d8ae267ba1e","repo":"huggingface/transformers","slug":"only-union-x-nonetype-i-e-optional-x-is","errorCode":null,"errorMessage":"Only `Union[X, NoneType]` (i.e., `Optional[X]`) is allowed for `Union` because the argument parser only supports one type per argument. Problem encountered in field '{field.name}'.","messagePattern":"Only `Union\\[X, NoneType\\]` \\(i\\.e\\., `Optional\\[X\\]`\\) is allowed for `Union` because the argument parser only supports one type per argument\\. Problem encountered in field '(.+?)'\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/hf_argparser.py","lineNumber":173,"sourceCode":"        kwargs = field.metadata.copy()\n        # field.metadata is not used at all by Data Classes,\n        # it is provided as a third-party extension mechanism.\n        if isinstance(field.type, str):\n            raise RuntimeError(\n                \"Unresolved type detected, which should have been done with the help of \"\n                \"`typing.get_type_hints` method by default\"\n            )\n\n        aliases = kwargs.pop(\"aliases\", [])\n        if isinstance(aliases, str):\n            aliases = [aliases]\n\n        origin_type = getattr(field.type, \"__origin__\", field.type)\n        if origin_type is Union or (hasattr(types, \"UnionType\") and isinstance(origin_type, types.UnionType)):\n            if str not in field.type.__args__ and (\n                len(field.type.__args__) != 2 or type(None) not in field.type.__args__\n            ):\n                raise ValueError(\n                    \"Only `Union[X, NoneType]` (i.e., `Optional[X]`) is allowed for `Union` because\"\n                    \" the argument parser only supports one type per argument.\"\n                    f\" Problem encountered in field '{field.name}'.\"\n                )\n            if type(None) not in field.type.__args__:\n                # filter `str` in Union\n                field.type = field.type.__args__[0] if field.type.__args__[1] is str else field.type.__args__[1]\n                origin_type = getattr(field.type, \"__origin__\", field.type)\n            elif bool not in field.type.__args__:\n                # filter `NoneType` in Union (except for `Union[bool, NoneType]`)\n                field.type = (\n                    field.type.__args__[0] if isinstance(None, field.type.__args__[1]) else field.type.__args__[1]\n                )\n                origin_type = getattr(field.type, \"__origin__\", field.type)\n\n        # A variable to store kwargs for a boolean field, if needed\n        # so that we can init a `no_*` complement argument (see below)\n        bool_kwargs = {}","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/hf_argparser.py#L155-L191","documentation":"Error \"Only `Union[X, NoneType]` (i.e., `Optional[X]`) is allowed for `Union` because the argument parser only supports one type per argument. Problem encountered in field '{field.name}'.\" thrown in huggingface/transformers.","triggerScenarios":"Raised in HfArgumentParser when a field is annotated Union of more than one non-None type.","commonSituations":"Using Union[int, str] in a TrainingArguments-style dataclass; only Optional[X] single-type unions are supported.","solutions":["Declare the field as `Optional[X]` instead of a multi-type `Union`.","Split the argument into separate fields if multiple types are truly needed."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}