apache/beam · error · CompositeTypeHintError

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

Error message

%s hint %s-type constraint violated. All %s should be of type %s. Instead: %s

What it means

Runtime type-check failure for a KV[K, V] constraint: one of the keys or values inside a provided tuple does not match its hinted type (the message says whether it is the key or value slot and shows the offending element). It is raised from type_check during pipeline execution when the hint's inner check fails.

Solutions

  1. Read the embedded inner message for the deepest failing constraint
  2. Fix the offending key/value to satisfy the composite hint
  3. Update the hint if the nested structure legitimately changed

Example fix

# before
Dict[str, Tuple[int, int]]: {'a': (1,)}
# after
{'a': (1, 2)}
Defensive patterns

Strategy: validation

Validate before calling

for k, v in d.items():
    if not (isinstance(v, tuple) and len(v) == 2): raise ValueError(f'value for {k!r} violates nested hint: {v!r}')

Type guard

def conforms(d, kcheck, vcheck): return isinstance(d, dict) and all(kcheck(k) and vcheck(v) for k, v in d.items())

Prevention

When it happens

Trigger: A key or value that must satisfy a composite hint (Tuple/List/Dict/Union) fails, e.g. Dict[str, Tuple[int, int]] receiving {'a': (1,)}; type_check catches CompositeTypeHintError and re-raises via this helper.

Common situations: Values built as nested structures whose inner shape drifted; keys built as tuples/Unions with wrong content.

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

Appendix: source

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

    def __hash__(self):
      return hash((type(self), self.key_type, self.value_type))

    def _inner_types(self):
      yield self.key_type
      yield self.value_type

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

    def _raise_hint_exception_or_inner_exception(
        self, is_key, incorrect_instance, inner_error_message=''):
      incorrect_type = 'values' if not is_key else 'keys'
      hinted_type = self.value_type if not is_key else self.key_type
      if inner_error_message:
        raise CompositeTypeHintError(
            '%s hint %s-type constraint violated. All %s should be of type '
            '%s. Instead: %s' % (
                repr(self),
                incorrect_type[:-1],
                incorrect_type,
                repr(hinted_type),
                inner_error_message))
      else:
        raise CompositeTypeHintError(
            '%s hint %s-type constraint violated. All %s should be of '
            'type %s. Instead, %s is of type %s.' % (
                repr(self),
                incorrect_type[:-1],
                incorrect_type,
                repr(hinted_type),
                incorrect_instance,
                incorrect_instance.__class__.__name__))

View on GitHub (pinned to 12126d8942)