apache/beam · error · CompositeTypeHintError

Window type-constraint violated. Valid object instance must…

Error message

Window type-constraint violated. Valid object instance must be of type 'WindowedValue'. Instead, an instance of '%s' was received.

What it means

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.

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

Example fix

// before
p | beam.Map(lambda x: x).with_output_types(WindowedValue[str])
// after
p | beam.Map(lambda x: window.TimestampedValue(x, timestamp)).with_output_types(WindowedValue[str])

Defensive patterns

Strategy: type-guard

Validate before calling

from apache_beam.transforms import window
assert isinstance(v, window.WindowedValue), type(v)

Type guard

def is_windowed_value(v):
    from apache_beam.transforms import window
    return isinstance(v, window.WindowedValue)

Try / catch

try:
    typecheck.validate(WindowedValue[str], v)
except CompositeTypeHintError as e:
    if 'WindowedValue' in str(e):
        v = window.TimestampedValue(v.value, v.timestamp)

Prevention

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

When it happens

Trigger: 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].

Common situations: 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.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/653618d5d35f5b3b. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/typehints/typehints.py:1387

    return (
        isinstance(other, WindowedTypeConstraint) and
        self.inner_type == other.inner_type)

  def __hash__(self):
    return hash(self.inner_type) ^ 13 * hash(type(self))

  def _inner_types(self):
    yield self.inner_type

  def _consistent_with_check_(self, sub):
    return (
        isinstance(sub, self.__class__) and
        is_consistent_with(sub.inner_type, self.inner_type))

  def type_check(self, instance):
    from apache_beam.transforms import window
    if not isinstance(instance, window.WindowedValue):
      raise CompositeTypeHintError(
          "Window type-constraint violated. Valid object instance "
          "must be of type 'WindowedValue'. Instead, an instance of '%s' "
          "was received." % (instance.__class__.__name__))

    try:
      check_constraint(self.inner_type, instance.value)
    except (CompositeTypeHintError, SimpleTypeHintError):
      raise CompositeTypeHintError(
          '%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.' % (
              repr(self),
              repr(self.inner_type),
              instance.value.__class__.__name__))

  def bind_type_variables(self, bindings):
    bound_inner_type = bind_type_variables(self.inner_type, bindings)
    if bound_inner_type == self.inner_type:

View on GitHub (pinned to 12126d8942)