apache/beam · error · CompositeTypeHintError

type-constraint violated. Expected an instance of one of: …

Error message

%s type-constraint violated. Expected an instance of one of: %s, received %s instead.%s

What it means

UnionTypeConstraint.type_check raises CompositeTypeHintError when an instance matches none of the types in a Union hint. Beam tries each union member with check_constraint, collecting the last TypeError message, and if all fail it reports the allowed alternatives and the received instance's class.

Solutions

1. Check the received type in the message and convert the value to one of the union's accepted types before the typed stage.
2. Widen the Union to include the actual type, e.g. Union[int, float, str], or use Optional[...] if None occurs.
3. Fix the producing transform to emit the declared type consistently.
4. Read the trailing error_msg for hints about why each alternative was rejected (e.g. an invalid member raising TypeError).

Example fix

# before
.with_output_types(Union[int, float])  # produces '3.14' as str
# after
.with_output_types(Union[int, float]) and beam.Map(lambda x: float(x))
# or widen: Union[int, float, str]

def matches_union(value, accepted=(int, float)):
    return isinstance(value, accepted)

def is_num_or_none(x):
    return x is None or isinstance(x, (int, float))

try:
    expand(pcoll)
except CompositeTypeHintError as e:
    if 'Expected an instance of one of' in str(e):
        logger.error('value matches no Union member: %s', e)
    raise

When it happens

Trigger: A value that is not any of Union[X, Y, ...] is passed to a transform typed with that Union, e.g. Union[int, float] receiving a str; also fires when a member's type_check raises TypeError for all alternatives (bad constraint params).

Common situations: Data pipelines where a field is 'int or float' but parsing yields str; None reaching a Union[int, float] (forgot to include Optional); version changes where a producer's return type shifted.

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

• Cannot create Union without a sequence of types.
• An Option type-hint only accepts a single type parameter.
• bad type
• batch type must be List[T] for element type T
• batch type must be np.ndarray or…

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

Appendix: source

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

      if isinstance(sub, UnionConstraint):
        # A union type is compatible if every possible type is compatible.
        # E.g. Union[A, B, C] > Union[A, B].
        return all(is_consistent_with(elem, self) for elem in sub.union_types)
      # Other must be compatible with at least one of this union's subtypes.
      # E.g. Union[A, B, C] > T if T > A or T > B or T > C.
      return any(is_consistent_with(sub, elem) for elem in self.union_types)

    def type_check(self, instance):
      error_msg = ''
      for t in self.union_types:
        try:
          check_constraint(t, instance)
          return
        except TypeError as e:
          error_msg = str(e)
          continue

      raise CompositeTypeHintError(
          '%s type-constraint violated. Expected an instance of one of: %s, '
          'received %s instead.%s' % (
              repr(self),
              tuple(repr(t) for t in self.union_types),
              instance.__class__.__name__,
              error_msg))

    def match_type_variables(self, concrete_type):
      sub_bindings = [
          match_type_variables(t, concrete_type) for t in self.union_types
          if is_consistent_with(concrete_type, t)
      ]
      if sub_bindings:
        return {
            var: Union[(sub[var] for sub in sub_bindings)]
            for var in set.intersection(
                *[set(sub.keys()) for sub in sub_bindings])
        }

View on GitHub (pinned to 12126d8942)