{"record":{"id":"6317281eb516e403","repo":"apache/beam","slug":"type-hint-violation-for-label-requires-hint-but-got-actual","errorCode":null,"errorMessage":"Type hint violation for '{label}': requires {hint} but got {actual_type} for {arg}\nFull type hint:\n{debug_str}","messagePattern":"Type hint violation for '(.+?)': requires (.+?) but got (.+?) for (.+?)\nFull type hint:\n(.+?)","errorType":"validation","errorClass":"TypeCheckError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/ptransform.py","lineNumber":1005,"sourceCode":"        split_producer_label = pvalueish.producer.full_label.split(\"/\")\n        producer_label = \"/\".join(\n            split_producer_label[:transform_nest_level + 1])\n        raise TypeCheckError(\n            f\"The transform '{self.label}' requires \"\n            f\"PCollections of type '{element_hint}' \"\n            f\"but was applied to a PCollection of type\"\n            f\" '{bindings[element_arg]}' \"\n            f\"(produced by the transform '{producer_label}'). \")\n\n      # Now check the side inputs.\n      for arg, hint in arg_hints:\n        if arg.startswith('__unknown__'):\n          continue\n        if hint is None:\n          continue\n        if not typehints.is_consistent_with(bindings.get(arg, typehints.Any),\n                                            hint):\n          raise TypeCheckError(\n              'Type hint violation for \\'{label}\\': requires {hint} but got '\n              '{actual_type} for {arg}\\nFull type hint:\\n{debug_str}'.format(\n                  label=self.label,\n                  hint=hint,\n                  actual_type=bindings[arg],\n                  arg=arg,\n                  debug_str=type_hints.debug_str()))\n\n  def _process_argspec_fn(self):\n    \"\"\"Returns an argspec of the function actually consuming the data.\n    \"\"\"\n    raise NotImplementedError\n\n  def make_fn(self, fn, has_side_inputs):\n    # TODO(silviuc): Add comment describing that this is meant to be overriden\n    # by methods detecting callables and wrapping them in DoFns.\n    return fn\n","sourceCodeStart":987,"sourceCodeEnd":1023,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/ptransform.py#L987-L1023","documentation":"Generic Beam type-hint check failure: when `type_check_inputs` runs, each declared input hint is compared against the actual runtime type hints of the incoming pvalueish. Inconsistency raises TypeCheckError with the transform label, required hint, actual type, offending argument name, and the full debug type hint string.","triggerScenarios":"A transform with declared input type hints (via `with_input_types`, typed DoFn annotations, or PTransform.type_check_inputs) receives a PCollection whose type hint is inconsistent with the declaration.","commonSituations":"Typed DoFns applied to loosely/incorrectly typed PCollections; using `Any`-implied producers downstream of strictly typed consumers; hints left stale after refactoring output element types.","solutions":["Fix the actual type flowing in: adjust the producing transform so its output matches the declared input hint.","Relax or correct the consumer's input hint via `with_input_types()` or typed DoFn annotations to reflect real data.","Add an explicit `beam.Map(...).with_output_types(ExpectedType)` adapter between the mismatched stages.","Inspect `Full type hint:` in the message to pinpoint exactly which argument diverged."],"exampleFix":"# before\nbeam.ParDo(WordCountFn()).with_input_types(int)\n# after\nbeam.ParDo(WordCountFn()).with_input_types(str)","handlingStrategy":"validation","validationCode":"from apache_beam import typehints\nassert typehints.is_consistent_with(actual_type, hint), f'{actual_type} != {hint}'","typeGuard":"def input_types_match(transform, pcoll):\n  from apache_beam import typehints\n  hint = transform.get_type_hints().input_types[0] if transform.get_type_hints().input_types else typehints.Any\n  return typehints.is_consistent_with(pcoll.element_type or typehints.Any, hint)","tryCatchPattern":"try:\n  out = pc | 'typed_step' >> MyFn()\nexcept TypeCheckError as e:\n  log.error('%s', e)\n  raise","preventionTips":["Use typed DoFn process signatures so hints stay in sync with code.","Convert element types explicitly with beam.Map and with_output_types between stages.","Review the 'Full type hint' debug output when a check fails instead of disabling checks."],"tags":["python","apache-beam","type-checking"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}