apache/beam · error · TypeCheckError

Pipeline type checking is enabled, however no output type-hi

Error message

Pipeline type checking is enabled, however no output type-hint was found for the PTransform %s

What it means

Raised when pipeline type checking is enabled (type_check_strictness == 'ALL_REQUIRED') and a PTransform being applied has no output type hints. Beam requires every transform to declare its output types so it can validate pipeline data flow at graph-construction time.

Source

Thrown at sdks/python/apache_beam/pipeline.py:867

          transform.get_type_hints().output_types is None):
        ptransform_name = '%s(%s)' % (transform.__class__.__name__, full_label)
        raise TypeCheckError(
            'Pipeline type checking is enabled, however no '
            'output type-hint was found for the '
            'PTransform %s' % ptransform_name)
    finally:
      self.transforms_stack.pop()
    return pvalueish_result

  def _assert_not_applying_PDone(
      self,
      pvalueish: Optional[pvalue.PValue],
      transform: ptransform.PTransform):
    if isinstance(pvalueish, pvalue.PDone) and isinstance(transform, ParDo):
      # If the input is a PDone, we cannot apply a ParDo transform.
      full_label = self._current_transform().full_label
      producer_label = pvalueish.producer.full_label
      raise TypeCheckError(
          f'Transform "{full_label}" was applied to the output of '
          f'"{producer_label}" but "{producer_label.split("/")[-1]}" '
          'produces no PCollections.')

  def _generate_unique_label(self, transform: str) -> str:
    """
    Given a transform, generate a unique label for it based on current label.
    """
    unique_suffix = uuid.uuid4().hex[:6]
    return '%s_%s' % (transform.label, unique_suffix)

  def _infer_result_type(
      self,
      transform: ptransform.PTransform,
      inputs: Sequence[Union[pvalue.PBegin, pvalue.PCollection]],
      result_pcollection: Union[pvalue.PValue, pvalue.DoOutputsTuple]) -> None:
    """Infer and set the output element type for a PCollection.

View on GitHub (pinned to 12126d8942)

Solutions

Annotate the DoFn/expand with output type hints, e.g. @beam.typehints.with_output_types or expand returning pvalue.PCollection.with_output_types(...)
Relax strictness by setting type_check_strictness to 'DEFAULT' in PipelineOptions if hints cannot be added
Add @typehints decorators on process/expand methods to declare element types

Example fix

// before
class MyDoFn(beam.DoFn):
    def process(self, element):
        yield str(element)
// after
class MyDoFn(beam.DoFn):
    @beam.typehints.with_output_types(str)
    def process(self, element):
        yield str(element)

Defensive patterns

Strategy: validation

Validate before calling

from apache_beam import typehints
if typehints.decorator.get_type_hints(my_transform_fn).output_types is None:
    raise ValueError('Transform lacks output type hints')

Type guard

from apache_beam.typehints import typehints

def has_output_hints(fn):
    return typehints.native_type_compatibility.convert_to_beam_type is not None and getattr(fn, '_beam_type_hints_output', None) is not None

Try / catch

try:
    result = pcoll | my_transform
except apache_beam.TypeCheckError as e:
    logging.warning('Missing type hints: %s — falling back to default strictness', e)

Prevention

Always annotate DoFn.process and PTransform.expand with typehints
Run pipelines with type checking in CI
Add @with_output_types to every custom transform

When it happens

Trigger: Running with --type_check_strictness=ALL_REQUIRED (or PipelineOptions type_check_strictness option) while applying a custom PTransform/DoFn whose output type hint (with_output_types) is missing.

Common situations: Custom DoFns or PTransforms written without @typehints decorators; upgrading Beam to stricter type checking defaults; third-party transforms lacking hints.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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