{"record":{"id":"ea49a77ded6ef705","repo":"apache/beam","slug":"the-transform-label-requires-pcollections-of-type-element","errorCode":null,"errorMessage":"The transform '{label}' requires PCollections of type '{element_hint}' but was applied to a PCollection of type '{bindings[element_arg]}' (produced by the transform '{producer_label}'). ","messagePattern":"The transform '(.+?)' requires PCollections of type '(.+?)' but was applied to a PCollection of type '(.+?)' \\(produced by the transform '(.+?)'\\)\\. ","errorType":"validation","errorClass":"TypeCheckError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/ptransform.py","lineNumber":990,"sourceCode":"        return instance_to_type(side_input)\n\n      arg_types = [pvalueish.element_type] + [element_type(v) for v in args]\n      kwargs_types = {k: element_type(v) for (k, v) in kwargs.items()}\n      argspec_fn = self._process_argspec_fn()\n      bindings = getcallargs_forhints(argspec_fn, *arg_types, **kwargs_types)\n      hints = getcallargs_forhints(\n          argspec_fn, *input_types[0], **input_types[1])\n\n      # First check the main input.\n      arg_hints = iter(hints.items())\n      element_arg, element_hint = next(arg_hints)\n      if not typehints.is_consistent_with(\n          bindings.get(element_arg, typehints.Any), element_hint):\n        transform_nest_level = self.label.count(\"/\")\n        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,","sourceCodeStart":972,"sourceCodeEnd":1008,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/ptransform.py#L972-L1008","documentation":"During pipeline type checking, Beam verifies that the PCollection fed into a transform has an element type consistent with the transform's declared element type hint (`element_arg`). If the producer's declared type is inconsistent, a TypeCheckError is raised naming the expected type, the actual type, and the upstream transform that produced the PCollection.","triggerScenarios":"Applying a transform (e.g. one with `with_input_types` or a GroupByKey-ish element hint) to a PCollection whose runtime type hint from the producing transform doesn't match, while pipeline type checking is enabled (default; disabled via --type_check_strictness or --no_type_check).","commonSituations":"Chaining transforms where an earlier map changed the element type without updating hints; mixing typed and untyped PCollections; copy-pasted pipeline fragments where a source transform's output type changed after a library upgrade.","solutions":["Read the producer transform named in the message and fix its output type or `with_output_types` hint so it matches what the consumer expects.","Update the consumer's declared element hint (`with_input_types`/typed DoFn `process` signature) to match the real data.","Insert an explicit conversion map (`beam.Map(convert_fn).with_output_types(T)`) between producer and consumer.","As a last resort, disable checking (`--type_check_strictness=ALL_REQUIRED` off / `--no_type_check`), but this hides real bugs."],"exampleFix":"# before\npc = (p | beam.Create(['1','2']) | beam.Map(int) | beam.Map(lambda x: x + 'x'))\n# after\npc = (p | beam.Create(['1','2']) | beam.Map(lambda x: str(int(x)) + 'x'))","handlingStrategy":"validation","validationCode":"from apache_beam import typehints\nassert typehints.is_consistent_with(producer_out_type, expected_element_type), \\\n  f'producer yields {producer_out_type}, transform needs {expected_element_type}'","typeGuard":"def matches_element_hint(pcoll, hint):\n  from apache_beam import typehints\n  return typehints.is_consistent_with(pcoll.element_type, hint)","tryCatchPattern":"try:\n  out = pc | 'step' >> MyTypedTransform()\nexcept TypeCheckError as e:\n  log.error('Type mismatch in pipeline: %s', e)\n  raise","preventionTips":["Annotate every transform with with_output_types/with_input_types so mismatches surface at the producing stage.","Run pipelines with type checking enabled locally before submitting to the runner.","Keep hints updated whenever an element type changes during refactoring."],"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"}