apache/beam · error · ValueError

Expected an instance of ShardedKeyTypeConstraint, but got a

Error message

Expected an instance of ShardedKeyTypeConstraint, but got a %s

What it means

ShardedKeyCoder encodes sharded keys and its from_type_hint only accepts typehints that are ShardedKeyTypeConstraint instances, from which it extracts the inner key coder. Passing any other typehint raises ValueError.

Source

Thrown at sdks/python/apache_beam/coders/coders.py:1781

  def _create_impl(self):
    return coder_impl.ShardedKeyCoderImpl(self._key_coder.get_impl())

  def is_deterministic(self):
    # type: () -> bool
    return self._key_coder.is_deterministic()

  def to_type_hint(self):
    from apache_beam.typehints import sharded_key_type
    return sharded_key_type.ShardedKeyTypeConstraint(
        self._key_coder.to_type_hint())

  @classmethod
  def from_type_hint(cls, typehint, registry):
    from apache_beam.typehints import sharded_key_type
    if isinstance(typehint, sharded_key_type.ShardedKeyTypeConstraint):
      return cls(registry.get_coder(typehint.key_type))
    else:
      raise ValueError((
          'Expected an instance of ShardedKeyTypeConstraint'
          ', but got a %s' % typehint))

  def __eq__(self, other):
    return type(self) == type(other) and self._key_coder == other._key_coder

  def __hash__(self):
    return hash(type(self)) + hash(self._key_coder)

  def __repr__(self):
    return 'ShardedKeyCoder[%s]' % self._key_coder


Coder.register_structured_urn(
    common_urns.coders.SHARDED_KEY.urn, ShardedKeyCoder)


class TimestampPrefixingWindowCoder(FastCoder):

View on GitHub (pinned to 12126d8942)

Solutions

1. Wrap the key typehint with apache_beam.typehints.sharded_key_type.ShardedKey[T] so the constraint instance is produced
2. Ensure the transform emitting the data is annotated with the ShardedKey typehint
3. Use the registry's normal coder resolution rather than forcing ShardedKeyCoder for non-sharded keys

Example fix

// before
ShardedKeyCoder.from_type_hint(str, registry)
// after
ShardedKeyCoder.from_type_hint(ShardedKey[str], registry)

from apache_beam.typehints import sharded_key_type
is_sharded = isinstance(typehint, sharded_key_type.ShardedKeyTypeConstraint)

def is_sharded_key_hint(th) -> bool:
    from apache_beam.typehints import sharded_key_type
    return isinstance(th, sharded_key_type.ShardedKeyTypeConstraint)

try:
    coder = ShardedKeyCoder.from_type_hint(typehint, registry)
except ValueError:
    coder = registry.get_coder(typehint)

When it happens

Trigger: Requesting a coder for a typehint that is not sharded_key_type.ShardedKeyTypeConstraint, e.g. registering ShardedKeyCoder for a plain dict/KV hint or a hand-built type constraint.

Common situations: Using sharded-key features (e.g. stateful/locking transforms expecting sharded keys) without wrapping the key type via ShardedKey; type-inference producing a bare key type.

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

• Typehint is not of nullable type, and cannot be converted to
• key_coder: %s
• Not a KV coder: %s.
• value_coder: %s
• ToBytesCoder cannot be used for decoding.

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/0f0234136026ba18. Report an issue: GitHub.