apache/beam · error · ValueError

'Cannot provide coder for

Error message

'Cannot provide coder for %s: %s' % (typehint, ';'.join(messages))

What it means

CoderRegistry.from_type_hint tries every registered coder plugin that claims to handle a type hint. If all of them fail, it aggregates each failure message and raises ValueError('Cannot provide coder for ...'). It means Beam could not determine any serialization strategy for the PCollection element type.

Solutions

Register a coder for your type: typecoders.registry.register_coder(MyType, MyCoder) or register_row for dataclasses/NamedTuples.
Read the appended per-coder messages to find the root exception in the failing plugin.
Convert elements to a natively supported type (dict, Row, bytes) before the transform.
If a custom coder is failing, fix the exception it raises in from_type_hint/to_type_hint.

Example fix

// before
pcf = pc | beam.Map(lambda x: MyRecord(x)) | beam.GroupByKey()  # no coder for MyRecord
// after
typecoders.registry.register_coder(MyRecord, MyRecordCoder)
pcf = pc | beam.Map(lambda x: MyRecord(x)) | beam.GroupByKey()

Defensive patterns

Strategy: try-catch

Validate before calling

# ensure a coder exists before building the pipeline
typecoders.registry.register_coder(MyType, MyCoder)
assert typecoders.registry.get_coder(MyType) is not None

Try / catch

try:
    run_pipeline(pcolls)
except ValueError as e:
    if 'Cannot provide coder for' in str(e):
        register_coders_for_user_types()  # then re-run
    else:
        raise

Prevention

Register coders for all custom element types before pipeline construction.
Prefer schema-aware types (beam.Row, dataclasses via register_row).
Read the per-coder messages appended to the error to find root causes.
Avoid relying on inference through lambdas; use typed functions or explicit type hints.

When it happens

Trigger: Running a pipeline whose PCollection element type is an arbitrary user class with no registered coder; a registered custom coder raising inside from_type_hint; using types (e.g. unhashable or exotic generics) no coder plugin supports.

Common situations: Passing custom Python objects through GroupByKey/GBK stages requiring coders; forgetting register_coder/register_row for a dataclass; a custom coder throwing during type-hint resolution masking the real error.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/coders/typecoders.py:258

class FirstOf(object):
  """For internal use only; no backwards-compatibility guarantees.

  A class used to get the first matching coder from a list of coders."""
  def __init__(self, coders: Iterable[type[coders.Coder]]) -> None:
    self._coders = coders

  def from_type_hint(self, typehint, registry):
    messages = []
    for coder in self._coders:
      try:
        return coder.from_type_hint(typehint, registry)
      except Exception as e:
        msg = (
            '%s could not provide a Coder for type %s: %s' %
            (coder, typehint, e))
        messages.append(msg)

    raise ValueError(
        'Cannot provide coder for %s: %s' % (typehint, ';'.join(messages)))


registry = CoderRegistry()

View on GitHub (pinned to 12126d8942)