apache/beam · error · CompositeTypeHintError

Dict type-constraint violated. All passed instances must be…

Error message

Dict type-constraint violated. All passed instances must be of type dict. %s is of type %s.

What it means

Runtime check in DictConstraint.type_check: a value passed under a Dict[K, V] typehint is not a dict at all (its actual type is shown), so the constraint is violated before per-key/per-value checks can even run.

Solutions

Convert to a plain dict before the hinted transform: dict(pairs)
Return None-check: ensure the value is not None
If using a custom Mapping, wrap or convert with dict(obj)

Example fix

# before
yield [(k, v) for k, v in ...]
# after
yield dict((k, v) for k, v in ...)

Defensive patterns

Strategy: type-guard

Validate before calling

if not isinstance(obj, dict): obj = dict(obj)

Type guard

def is_dict(x): return isinstance(x, dict)

Prevention

Convert list-of-pairs and custom Mappings with dict(...) before hint checks
Guard against None before returning dict-typed values

When it happens

Trigger: Passing a list of pairs, an OrderedDict-like custom mapping, or None where a dict is hinted; a DoFn yielding list(zip(keys, values)) instead of dict(zip(...)).

Common situations: Confusing list-of-tuples with dict; third-party mapping types not subclassing dict; returning defaultdict works (isinstance dict) but custom Mapping wrappers do not.

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

Appendix: source

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

                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:
          check_constraint(self.key_type, key)
        except CompositeTypeHintError as e:
          self._raise_hint_exception_or_inner_exception(True, key, str(e))
        except SimpleTypeHintError:
          self._raise_hint_exception_or_inner_exception(True, key)

        try:
          check_constraint(self.value_type, value)
        except CompositeTypeHintError as e:
          self._raise_hint_exception_or_inner_exception(False, value, str(e))
        except SimpleTypeHintError:
          self._raise_hint_exception_or_inner_exception(False, value)

View on GitHub (pinned to 12126d8942)