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

What it means

Raised when a runtime type-check (type_check=True pipelines or direct assertions) finds that a key of a Dict/Mapping instance violates the declared key-type constraint. The inner_error_message branch is used when the key itself failed a composite (nested) constraint, so the inner error text is appended instead of a simple class name. It is a CompositeTypeHintError, i.e. a nested validation failure.

Solutions

Coerce keys to the declared key type before yielding/returning the mapping (e.g. str(k))
Correct the type hint to match the actual key type: Dict[int, V] if keys are ints
Disable/relax runtime type checking via --type_check=none if the violation is intentional (last resort)

Example fix

// before
p | beam.Map(lambda d: {i: v for i, v in enumerate(d)}).with_output_types(Dict[str, str])
// after
p | beam.Map(lambda d: {str(i): v for i, v in enumerate(d)}).with_output_types(Dict[str, str])

Defensive patterns

Strategy: type-guard

Validate before calling

import collections.abc
ok = isinstance(d, collections.abc.Mapping) and all(isinstance(k, str) for k in d)
# ok must be True before passing data through a Dict[str, V] annotated op

Type guard

def matches_dict_hint(d, key_type, value_type):
    return isinstance(d, collections.abc.Mapping) and all(
        isinstance(k, key_type) for k in d.keys())

Try / catch

from apache_beam.typehints.exceptions import CompositeTypeHintError
try:
    typecheck.validate(hint, instance)
except CompositeTypeHintError as e:
    log.error('key type violation: %s', e)

Prevention

Keep key types consistent at data boundaries (e.g. always str keys from JSON)
Run pipelines with --type_check=strict in CI to catch violations early
Coerce key types where data enters the pipeline

When it happens

Trigger: A dict whose keys are not of the declared key_type is passed through an op annotated with Dict[K, V] while type checking is enabled (e.g. beam.Map with .with_output_types(Dict[str, int]) returning {1: ...}), or a nested composite key type fails its own constraint.

Common situations: Pipeline options enable type_check=True (default in newer Beam versions); a DoFn yields dicts built from heterogeneous data where keys are ints but the hint says str; converting data from JSON whose keys are always strings while the hint expects ints.

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

Appendix: source

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

            is_consistent_with(sub.key_type, self.key_type) and
            is_consistent_with(sub.value_type, self.value_type))
      elif hasattr(sub, '__origin__'):
        # Handle collection subtypes using ABC
        if issubclass(sub.__origin__, abc.Mapping):
          args = getattr(sub, '__args__', None)
          if args and len(args) == 2:
            return (
                is_consistent_with(args[0], self.key_type) and
                is_consistent_with(args[1], self.value_type))
          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__,

View on GitHub (pinned to 12126d8942)