apache/beam · error · CompositeTypeHintError

hint -type constraint violated. All %ss should be of type …

Error message

%s hint %s-type constraint violated. All %ss should be of type %s. Instead, %s is of type %s.

What it means

Raised when a value (or key) in a Dict/Mapping fails its declared type constraint and no nested composite error message exists — the report names the offending instance and its concrete class. It is thrown from Dict.type_check / Mapping.type_check while iterating items during runtime type validation.

Solutions

Fix the producer so every value matches the declared value type, or convert values (e.g. int(v))
Widen the hint to the actual common type (e.g. Union[int, float]) or use Any
Skip/validate bad records before building the mapping

Example fix

// before
p | beam.Map(lambda d: {k: v for k, v in d.items()}).with_output_types(Dict[str, int])  # v can be float
// after
p | beam.Map(lambda d: {k: int(v) for k, v in d.items()}).with_output_types(Dict[str, int])

Defensive patterns

Strategy: validation

Validate before calling

ok = all(isinstance(v, value_type) for v in d.values())
# assert ok before emitting the mapping

Type guard

def values_match_hint(d, value_type):
    return isinstance(d, collections.abc.Mapping) and all(
        isinstance(v, value_type) for v in d.values())

Try / catch

try:
    typecheck.validate(Dict[str, int], result)
except CompositeTypeHintError as e:
    log.error('value type violation: %s', e)
    result = {k: int(v) for k, v in result.items()}

Prevention

Normalize value types at ingestion (ints, floats, None handling)
Avoid Optional values under non-Optional hints; use Union[V, None] explicitly
Add unit assertions on DoFn outputs before enabling runtime checks

When it happens

Trigger: Returning a mapping annotated Dict[K, V] where some value is of a different class, e.g. .with_output_types(Dict[str, int]) but the dict contains {"a": 1.5} (float values), while type_check is enabled.

Common situations: Optional/None values slipping in (None is not the declared type); numpy numbers vs python ints; a lambda producing heterogeneous values; data schema drift after an upstream source change.

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

Appendix: source

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

          return True
      return False

    def _raise_type_error(self, is_key, instance, inner_error_message=''):
      type_desc = 'key' if is_key else 'value'
      expected_type = self.key_type if is_key else self.value_type

      if inner_error_message:
        raise CompositeTypeHintError(
            '%s hint %s-type constraint violated. All %ss should be of type '
            '%s. Instead: %s' % (
                repr(self),
                type_desc,
                type_desc,
                repr(expected_type),
                inner_error_message,
            ))
      else:
        raise CompositeTypeHintError(
            '%s hint %s-type constraint violated. All %ss should be of '
            'type %s. Instead, %s is of type %s.' % (
                repr(self),
                type_desc,
                type_desc,
                repr(expected_type),
                instance,
                instance.__class__.__name__,
            ))

    def type_check(self, instance):
      if not isinstance(instance, abc.Mapping):
        raise CompositeTypeHintError(
            'Mapping type-constraint violated. All passed instances must be of '
            'type Mapping. %s is of type %s.' %
            (instance, instance.__class__.__name__))

      for key, value in instance.items():

View on GitHub (pinned to 12126d8942)