{"record":{"id":"cfd892a5b1d9db93","repo":"apache/beam","slug":"type-type-hint-violation-at-label-context-expected-hint-got","errorCode":null,"errorMessage":"{type} type hint violation at {label}{context}: expected {hint}, got {actual_type}","messagePattern":"(.+?) type hint violation at (.+?)(.+?): expected (.+?), got (.+?)","errorType":"validation","errorClass":"TypeCheckError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/ptransform.py","lineNumber":513,"sourceCode":"      return\n    arg_hints, kwarg_hints = hints\n    # Output types can have kwargs for tagged output types.\n    if arg_hints and kwarg_hints and input_or_output != 'output':\n      raise TypeCheckError(\n          'PTransform cannot have both positional and keyword input type hints'\n          ' without overriding %s._type_check_%s()' %\n          (self.__class__, input_or_output))\n    root_hint = (\n        arg_hints[0] if len(arg_hints) == 1 else arg_hints or kwarg_hints)\n    for context, pvalue_, hint in _ZipPValues().visit(pvalueish, root_hint):\n      if isinstance(pvalue_, DoOutputsTuple):\n        continue\n      if pvalue_.element_type is None:\n        # TODO(robertwb): It's a bug that we ever get here. (typecheck)\n        continue\n      if hint and not typehints.is_consistent_with(pvalue_.element_type, hint):\n        at_context = ' %s %s' % (input_or_output, context) if context else ''\n        raise TypeCheckError(\n            '{type} type hint violation at {label}{context}: expected {hint}, '\n            'got {actual_type}'.format(\n                type=input_or_output.title(),\n                label=self.label,\n                context=at_context,\n                hint=hint,\n                actual_type=pvalue_.element_type))\n\n  def _infer_output_coder(self, input_type=None, input_coder=None):\n    # type: (...) -> Optional[coders.Coder]\n\n    \"\"\"Returns the output coder to use for output of this transform.\n\n    The Coder returned here should not be wrapped in a WindowedValueCoder\n    wrapper.\n\n    Args:\n      input_type: An instance of an allowed built-in type, a custom class, or a","sourceCodeStart":495,"sourceCodeEnd":531,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/ptransform.py#L495-L531","documentation":"When Beam type-checks PTransform inputs/outputs, each PCollection's element_type must be consistent with the declared type hint. If typehints.is_consistent_with fails, a TypeCheckError pinpointing the transform label and position is raised.","triggerScenarios":"Applying a transform whose declared input/output hint doesn't match the actual element_type of the PCollection at runtime — e.g. hinting int while the PCollection holds str, or mismatched dict value types.","commonSituations":"Chaining transforms where an upstream transform changes element type silently; stale hints after refactoring; wrong hints on tagged outputs.","solutions":["Fix the type hint to match actual element types (or vice versa) as indicated in the message.","Verify the upstream PCollection's element_type (p.element_type) before applying the transform.","Temporarily disable runtime type checking (e.g. pipeline options --runtime_type_check=False or type_check=False) to isolate where hints drift."],"exampleFix":"// before\np | beam.Map(lambda x: str(x)).with_output_types(int)\n// after\np | beam.Map(lambda x: str(x)).with_output_types(str)","handlingStrategy":"try-catch","validationCode":"from apache_beam import typehints\nassert typehints.is_consistent_with(pc.element_type, declared_hint), f\"{pc.element_type} not consistent with {declared_hint}\"","typeGuard":null,"tryCatchPattern":"try:\n  out = pcoll | transform\nexcept TypeCheckError as e:\n  print(f\"Hint mismatch at {e}; check upstream element_type: {pcoll.element_type}\")\n  raise","preventionTips":["Verify pcoll.element_type before chaining transforms","Keep hints in sync when refactoring element types"],"tags":["python","apache-beam","type-hints"],"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"}