{"record":{"id":"653618d5d35f5b3b","repo":"apache/beam","slug":"window-type-constraint-violated-valid-object-instance-must","errorCode":null,"errorMessage":"Window type-constraint violated. Valid object instance must be of type 'WindowedValue'. Instead, an instance of '%s' was received.","messagePattern":"Window type-constraint violated\\. Valid object instance must be of type 'WindowedValue'\\. Instead, an instance of '(.+?)' was received\\.","errorType":"exception","errorClass":"CompositeTypeHintError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/typehints.py","lineNumber":1387,"sourceCode":"    return (\n        isinstance(other, WindowedTypeConstraint) and\n        self.inner_type == other.inner_type)\n\n  def __hash__(self):\n    return hash(self.inner_type) ^ 13 * hash(type(self))\n\n  def _inner_types(self):\n    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:","sourceCodeStart":1369,"sourceCodeEnd":1405,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/typehints.py#L1369-L1405","documentation":"WindowedValue[T] hints require runtime instances to be apache_beam.transforms.window.WindowedValue objects. Beam's type_check raises CompositeTypeHintError if the checked instance is any other class. This is an internal-oriented hint mostly used for window-aware values.","triggerScenarios":"Annotating a PCollection/DoFn output with WindowedValue[T] while emitting plain (unwrapped) values, or passing a raw value to a type_check/assert against WindowedValue[T].","commonSituations":"Manually constructing windowed pipelines and forgetting window.TimestampedValue/WindowedValue wrapping; applying WindowedValue hints to results of a Map that returns bare elements; unit tests feeding plain values.","solutions":["Wrap values in a WindowedValue (or TimestampedValue) before yielding: window.TimestampedValue(value, timestamp)","Remove the WindowedValue[...] wrapper from the hint if you actually deal with bare values","Ensure the transform that should produce windowed values (e.g. after windowing) is the one annotated"],"exampleFix":"// before\np | beam.Map(lambda x: x).with_output_types(WindowedValue[str])\n// after\np | beam.Map(lambda x: window.TimestampedValue(x, timestamp)).with_output_types(WindowedValue[str])","handlingStrategy":"type-guard","validationCode":"from apache_beam.transforms import window\nassert isinstance(v, window.WindowedValue), type(v)","typeGuard":"def is_windowed_value(v):\n    from apache_beam.transforms import window\n    return isinstance(v, window.WindowedValue)","tryCatchPattern":"try:\n    typecheck.validate(WindowedValue[str], v)\nexcept CompositeTypeHintError as e:\n    if 'WindowedValue' in str(e):\n        v = window.TimestampedValue(v.value, v.timestamp)","preventionTips":["Only use WindowedValue[...] hints on windowing-aware transforms","Wrap payloads with TimestampedValue/WindowedValue before emitting","Keep WindowedValue hints out of plain Map outputs unless values are wrapped"],"tags":["python","apache-beam","type-hints","windowing"],"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"}