{"record":{"id":"de18db26139e2cbb","repo":"apache/beam","slug":"s-hint-type-constraint-violated-the-type-of-element-in-is","errorCode":null,"errorMessage":"%s hint type-constraint violated. The type of element in is incorrect. Expected an instance of type %s, instead received an instance of type %s.","messagePattern":"(.+?) hint type-constraint violated\\. The type of element in is incorrect\\. Expected an instance of type (.+?), instead received an instance of type (.+?)\\.","errorType":"exception","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":1395,"sourceCode":"    yield self.inner_type\n\n  def _consistent_with_check_(self, sub):\n    return (\n        isinstance(sub, self.__class__) and\n        is_consistent_with(sub.inner_type, self.inner_type))\n\n  def type_check(self, instance):\n    from apache_beam.transforms import window\n    if not isinstance(instance, window.WindowedValue):\n      raise CompositeTypeHintError(\n          \"Window type-constraint violated. Valid object instance \"\n          \"must be of type 'WindowedValue'. Instead, an instance of '%s' \"\n          \"was received.\" % (instance.__class__.__name__))\n\n    try:\n      check_constraint(self.inner_type, instance.value)\n    except (CompositeTypeHintError, SimpleTypeHintError):\n      raise CompositeTypeHintError(\n          '%s hint type-constraint violated. The type of element in '\n          'is incorrect. Expected an instance of type %s, '\n          'instead received an instance of type %s.' % (\n              repr(self),\n              repr(self.inner_type),\n              instance.value.__class__.__name__))\n\n  def bind_type_variables(self, bindings):\n    bound_inner_type = bind_type_variables(self.inner_type, bindings)\n    if bound_inner_type == self.inner_type:\n      return self\n    return WindowedValue[bound_inner_type]\n\n  def __repr__(self):\n    return 'WindowedValue[%s]' % repr(self.inner_type)\n\n\nclass GeneratorHint(IteratorHint):","sourceCodeStart":1377,"sourceCodeEnd":1413,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L1377-L1413","documentation":"When a WindowedValue[T] instance passes the windowed-value check but its wrapped .value fails the inner type constraint, Beam raises this CompositeTypeHintError describing the expected inner type and the actual class of the wrapped value.","triggerScenarios":"Emitting window.TimestampedValue(bad_value, ts) through an output hinted WindowedValue[T] with type checking enabled, where bad_value is not of type T (e.g. T=str but value is bytes or None).","commonSituations":"Timestamped/Windowed pipelines where payload types change due to upstream parsing differences; yielding None payloads with a non-Optional inner hint; bytes vs str mismatches from binary sources.","solutions":["Fix the payload so instance.value matches the hinted inner type T, or convert it (str(v), etc.)","Relax the inner hint to match actual payload type (e.g. WindowedValue[Union[str, bytes]])","Validate payload type before wrapping in TimestampedValue/WindowedValue"],"exampleFix":"// before\np | beam.Map(lambda x: TimestampedValue(x, ts)).with_output_types(WindowedValue[str])  # x is bytes\n// after\np | beam.Map(lambda x: TimestampedValue(x.decode('utf-8'), ts)).with_output_types(WindowedValue[str])","handlingStrategy":"validation","validationCode":"from apache_beam.transforms import window\nassert isinstance(v, window.WindowedValue) and isinstance(v.value, inner_type)","typeGuard":"def is_windowed_of(v, inner_type):\n    from apache_beam.transforms import window\n    return isinstance(v, window.WindowedValue) and isinstance(v.value, inner_type)","tryCatchPattern":"try:\n    typecheck.validate(WindowedValue[str], v)\nexcept CompositeTypeHintError as e:\n    if 'element in' in str(e):\n        v = window.TimestampedValue(str(v.value), v.timestamp)","preventionTips":["Type-check payloads before wrapping in TimestampedValue","Use Union hints for payloads that can legitimately vary (bytes/str, Optional)","Keep payload transformation and windowing steps tested together"],"tags":["python","apache-beam","type-hints","windowing","runtime-type-check"],"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"}