apache/beam · error · RuntimeError

Coder registry has no fallback coder. This can happen if…

Error message

Coder registry has no fallback coder. This can happen if the fast_coders module could not be imported.

What it means

When no coder is registered for a type hint, the CoderRegistry falls back to a default coder that is installed at import time (typically the fast coders module). If the module-level initialization was skipped or failed (e.g. fast_coders could not be imported), the registry has no _fallback_coder attribute and get_coder raises this RuntimeError.

Solutions

1. Reinstall apache_beam from a wheel so compiled fast_coders extensions are present (pip install --force-reinstall apache_beam).
2. Check import of apache_beam.coders.coders_fast for ImportError and fix the underlying extension issue.
3. Avoid hand-instantiating CoderRegistry; use the module-level `registry` in typecoders which has the fallback set.
4. As a workaround, register an explicit coder for the typehint so the fallback is never consulted.

Example fix

// before
from apache_beam.coders.typecoders import CoderRegistry
coder = CoderRegistry().get_coder(my_typehint)
// after
from apache_beam.coders import typecoders
coder = typecoders.registry.get_coder(my_typehint)  # fallback initialized at import

from apache_beam.coders import coders_fast  # ImportError means fast coders missing
registry_has_fallback = hasattr(typecoders.registry, '_fallback_coder')

def fallback_available() -> bool:
    return hasattr(typecoders.registry, '_fallback_coder')

try:
    coder = registry.get_coder(typehint)
except RuntimeError as e:
    if 'no fallback coder' in str(e):
        reinstall_beam_or_register_explicit_coder(typehint)
    else:
        raise

When it happens

Trigger: Calling registry.get_coder(typehint) for an unregistered type when module init failed — typically because the compiled fast_coders C extension is missing or failed to import, or calling get_coder on a manually constructed CoderRegistry() before fallback setup.

Common situations: Broken/partial apache_beam installs missing compiled extensions; environments where cython/fast coder wheels are unavailable; tests instantiating a fresh registry without invoking the setup that assigns the fallback.

Related errors

• Bad coder for input of
• Bad coder for output of
• Cannot find default Beam SDK tar file
• 'Cannot provide coder for
• Coder registration requires a coder class object. Received…

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

Appendix: source

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

    typing_to_runner_api(typehint_type)
    return typehint_type

  def get_coder(self, typehint: Any) -> coders.Coder:
    if typehint and typehint.__module__ == '__main__':
      # See https://github.com/apache/beam/issues/21541
      # TODO(robertwb): Remove once all runners are portable.
      typehint = getattr(typehint, '__name__', str(typehint))
    coder = self._coders.get(
        typehint.__class__
        if isinstance(typehint, typehints.TypeConstraint) else typehint,
        None)
    if isinstance(typehint, typehints.TypeConstraint) and coder is not None:
      return coder.from_type_hint(typehint, self)
    if coder is None:
      # We use the fallback coder when there is no coder registered for a
      # typehint. For example a user defined class with no coder specified.
      if not hasattr(self, '_fallback_coder'):
        raise RuntimeError(
            'Coder registry has no fallback coder. This can happen if the '
            'fast_coders module could not be imported.')
      if isinstance(typehint, typehints.IterableTypeConstraint):
        return coders.IterableCoder.from_type_hint(typehint, self)
      elif isinstance(typehint, typehints.ListConstraint):
        return coders.ListCoder.from_type_hint(typehint, self)
      elif typehints.is_nullable(typehint):
        return coders.NullableCoder.from_type_hint(typehint, self)
      elif typehint is None:
        # In some old code, None is used for Any.
        # TODO(robertwb): Clean this up.
        pass
      elif typehint is object or typehint == typehints.Any:
        # We explicitly want the fallback coder.
        pass
      elif isinstance(typehint, typehints.TypeVariable):
        # TODO(robertwb): Clean this up when type inference is fully enabled.
        pass

View on GitHub (pinned to 12126d8942)