apache/beam · error · TypeError

Typehint is not of nullable type, and cannot be converted to

Error message

Typehint is not of nullable type, and cannot be converted to a NullableCoder

What it means

NullableCoder.from_type_hint() builds a NullableCoder that wraps the coder for the inner type, but only accepts type hints recognized as nullable by apache_beam.typehints. If the typehint is not a nullable type (e.g. Optional[...] was not used or a plain type was passed), the constructor path cannot proceed and a TypeError is raised.

Source

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

  def _create_impl(self):
    return coder_impl.NullableCoderImpl(self._value_coder.get_impl())

  def to_type_hint(self):
    return typehints.Optional[self._value_coder.to_type_hint()]

  def _get_component_coders(self):
    # type: () -> List[Coder]
    return [self._value_coder]

  @classmethod
  def from_type_hint(cls, typehint, registry):
    if typehints.is_nullable(typehint):
      return cls(
          registry.get_coder(
              typehints.get_concrete_type_from_nullable(typehint)))
    else:
      raise TypeError(
          'Typehint is not of nullable type, '
          'and cannot be converted to a NullableCoder',
          typehint)

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

  def as_deterministic_coder(self, step_label, error_message=None):
    if self.is_deterministic():
      return self
    else:
      deterministic_value_coder = self._value_coder.as_deterministic_coder(
          step_label, error_message)
      return NullableCoder(deterministic_value_coder)

  def __eq__(self, other):
    return (

View on GitHub (pinned to 12126d8942)

Solutions

1. Check that the typehint passed to from_type_hint is actually a nullable type such as Optional[T] or typehints.Nullable[T]
2. Use typehints.get_concrete_type_from_nullable to inspect what inner type would be extracted and confirm the hint shape
3. If the value cannot be None, register a plain coder for the concrete type instead of NullableCoder
4. Trace where the typehint originates (PDone/DoFn annotations) and fix the annotation to Optional[...]

Example fix

// before
NullableCoder.from_type_hint(int, registry)
// after
NullableCoder.from_type_hint(Optional[int], registry)

from apache_beam.typehints import typehints
if typehints.is_nullable(typehint):
    coder = NullableCoder.from_type_hint(typehint, registry)

def is_nullable_hint(th) -> bool:
    from apache_beam.typehints import typehints
    return typehints.is_nullable(th)

try:
    coder = NullableCoder.from_type_hint(typehint, registry)
except TypeError as e:
    coder = registry.get_coder(typehints.get_concrete_type(typehint))

When it happens

Trigger: Calling NullableCoder.from_type_hint(typehint, registry) with a typehint for which typehints.is_nullable() returns False, e.g. a bare int/str hint or a non-Optional generic.

Common situations: Pipelines where a PTransform's output type was inferred as non-nullable but the coder registry still attempts to build a NullableCoder; usually a symptom of a type-hint mismatch between the pipeline graph and registered coders.

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

• Expected an instance of ShardedKeyTypeConstraint, but got a
• 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/8124b36df010e402. Report an issue: GitHub.