apache/beam · error · CompositeTypeHintError

type-constraint violated. The type of key in 'ShardedKey'…

Error message

%s type-constraint violated. The type of key in 'ShardedKey' is incorrect. Expected an instance of type '%s', instead received an instance of type '%s'.

What it means

After confirming the instance is a ShardedKey, ShardedKeyType.type_check validates the inner key against self.key_type via check_constraint. If the key's type does not match the declared ShardedKey[K] parameter, it re-raises as CompositeTypeHintError describing the expected and actual key types.

Solutions

Align the key type with the declared hint, converting explicitly (e.g. int(sk.key)).
Update the PCollection's with_output_types annotation to the actual key type (ShardedKey[str]).
Audit the DoFn that creates the ShardedKey to ensure it produces the documented key type.

Example fix

// before
out | beam.Map(lambda k: ShardedKey(str(k), 1)).with_output_types(ShardedKey[int])
// after
out | beam.Map(lambda k: ShardedKey(int(k), 1)).with_output_types(ShardedKey[int])

Defensive patterns

Strategy: validation

Validate before calling

from apache_beam.typehints import check_constraint, ShardedKey
check_constraint(ShardedKey[int], ShardedKey(42, 1))  # raises before pipeline run if key type is wrong

Type guard

def is_sharded_key_of(v, key_type) -> bool:
    from apache_beam.typehints.sharded_key_type import ShardedKey
    return isinstance(v, ShardedKey) and isinstance(v.key, key_type)

Try / catch

try:
    run_pipeline(pipeline)
except apache_beam.typehints.TypeCheckError as e:
    log.error('ShardedKey inner key type mismatch: %s', e)

Prevention

Convert keys explicitly at boundaries between stages with different key encodings.
Declare ShardedKey hints only where the key type is guaranteed.
Test producing transforms with runtime type checks on.

When it happens

Trigger: A ShardedKey instance whose .key is of the wrong type reaches a runtime type check, e.g. a ShardedKey containing a str while the hint is ShardedKey[int] — typically from mismatched upstream/downstream typing.

Common situations: Mixing key encodings across pipeline stages (string IDs vs int IDs), or sharding a differently-typed key after a reshape and re-annotating with the old ShardedKey hint.

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

Appendix: source

Thrown at sdks/python/apache_beam/typehints/sharded_key_type.py:61

  def _inner_types(self):
    yield self.key_type

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

  def type_check(self, instance):
    if not isinstance(instance, ShardedKey):
      raise typehints.CompositeTypeHintError(
          "ShardedKey type-constraint violated. Valid object instance "
          "must be of type 'ShardedKey'. Instead, an instance of '%s' "
          "was received." % (instance.__class__.__name__))

    try:
      typehints.check_constraint(self.key_type, instance.key)
    except (typehints.CompositeTypeHintError, typehints.SimpleTypeHintError):
      raise typehints.CompositeTypeHintError(
          "%s type-constraint violated. The type of key in 'ShardedKey' "
          "is incorrect. Expected an instance of type '%s', "
          "instead received an instance of type '%s'." %
          (repr(self), repr(self.key_type), instance.key.__class__.__name__))

  def match_type_variables(self, concrete_type):
    if isinstance(concrete_type, ShardedKeyTypeConstraint):
      return typehints.match_type_variables(
          self.key_type, concrete_type.key_type)
    return {}

  def __eq__(self, other):
    return isinstance(
        other, ShardedKeyTypeConstraint) and self.key_type == other.key_type

  def __hash__(self):
    return hash(self.key_type)

View on GitHub (pinned to 12126d8942)