apache/beam · error · CompositeTypeHintError

hint type-constraint violated. The type of element in is…

Error message

%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.

What it means

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.

Solutions

  1. Fix the payload so instance.value matches the hinted inner type T, or convert it (str(v), etc.)
  2. Relax the inner hint to match actual payload type (e.g. WindowedValue[Union[str, bytes]])
  3. Validate payload type before wrapping in TimestampedValue/WindowedValue

Example fix

// before
p | beam.Map(lambda x: TimestampedValue(x, ts)).with_output_types(WindowedValue[str])  # x is bytes
// after
p | beam.Map(lambda x: TimestampedValue(x.decode('utf-8'), ts)).with_output_types(WindowedValue[str])
Defensive patterns

Strategy: validation

Validate before calling

from apache_beam.transforms import window
assert isinstance(v, window.WindowedValue) and isinstance(v.value, inner_type)

Type guard

def is_windowed_of(v, inner_type):
    from apache_beam.transforms import window
    return isinstance(v, window.WindowedValue) and isinstance(v.value, inner_type)

Try / catch

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

Prevention

When it happens

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

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

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/de18db26139e2cbb. Report an issue: GitHub.

Appendix: source

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

    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:
      return self
    return WindowedValue[bound_inner_type]

  def __repr__(self):
    return 'WindowedValue[%s]' % repr(self.inner_type)


class GeneratorHint(IteratorHint):

View on GitHub (pinned to 12126d8942)