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 is of type %s.

What it means

Raised by DictConstraint's _raise_hint_exception_or_inner_exception when a dict key or value fails a simple-type check; it names the offending instance and its runtime class. Emitted from type_check for every key/value pair scanned.

Solutions

Coerce or fix the reported key/value to the hinted type
Filter or transform offending entries before the hinted transform
Widen the hint, e.g. Dict[str, Union[int, str]] or Optional values
Add upstream validation of dict entries

Example fix

# before
Dict[str, int]: {'a': '5'}
# after
{'a': int('5')}

Defensive patterns

Strategy: validation

Validate before calling

bad = [(k, type(v).__name__) for k, v in d.items() if not isinstance(v, int)]
if bad: raise ValueError(f'non-int values: {bad}')

Type guard

def all_values_type(d, t): return isinstance(d, dict) and all(isinstance(v, t) for v in d.values())

Prevention

Coerce value types when building dicts from parsed data
Use Union[...] hints for legitimately mixed values

When it happens

Trigger: {'a': 'x'} against Dict[str, int]; an int key against Dict[str, int]; None values where a concrete type is hinted.

Common situations: JSON-parsed dicts with mixed value types; inconsistent records merged into one dict; Optional values not wrapped in Optional[...] hints.

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

Appendix: source

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

          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__))

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

      for key, value in dict_instance.items():
        try:

View on GitHub (pinned to 12126d8942)