apache/beam · error · RuntimeError

Unable to translate {self.full_label}

Error message

Unable to translate {self.full_label}

What it means

RuntimeError (wrapping the original exception) raised when AppliedPTransform.to_runner_api cannot convert the transform to its runner-api representation via transform_to_runner_api. It indicates the transform could not be serialized — usually because its URN/type is unregistered or its payload construction failed.

Source

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

        return None
      else:
        # We only populate inputs information to ParDo in order to expose
        # key_coder and window_coder to stateful DoFn.
        if isinstance(transform, ParDo):
          return transform.to_runner_api(
              context,
              has_parts=bool(self.parts),
              named_inputs=self.named_inputs())
        elif hasattr(transform, 'to_runner_api'):
          return transform.to_runner_api(context, has_parts=bool(self.parts))
        return None

    # Iterate over inputs and outputs by sorted key order, so that ids are
    # consistently generated for multiple runs of the same pipeline.
    try:
      transform_spec = transform_to_runner_api(self.transform, context)
    except Exception as exn:
      raise RuntimeError(f'Unable to translate {self.full_label}') from exn
    environment_id = self.environment_id
    transform_urn = transform_spec.urn if transform_spec else None
    if (not environment_id and
        (transform_urn not in Pipeline.runner_implemented_transforms())):
      environment_id = context.get_environment_id_for_resource_hints(
          self.resource_hints)
    if self.transform is not None:
      display_data = DisplayData.create_from(
          self.transform, extra_items=self.display_data)
    else:
      display_data = None

    return beam_runner_api_pb2.PTransform(
        unique_name=self.full_label,
        spec=transform_spec,
        subtransforms=[
            context.transforms.get_id(part, label=part.full_label)
            for part in self.parts

View on GitHub (pinned to 12126d8942)

Solutions

  1. Read the chained 'from exn' cause for the real root error and fix that (e.g. unpicklable lambda, missing URN registration)
  2. Register the custom transform's URN via the transforms registry or use standard Beam transforms
  3. If running with a portable runner, replace lambda-based DoFns with top-level functions/classes

Example fix

// before
result = pcoll | beam.Map(lambda x: (x, x * 2))
// after
def multiply(x):
    return (x, x * 2)
result = pcoll | beam.Map(multiply)
Defensive patterns

Strategy: try-catch

Validate before calling

import pickle
try:
    pickle.dumps(my_transform)
except Exception as e:
    print('Transform not serializable:', e)

Try / catch

try:
    proto = p.to_runner_api(context=ctx)
except RuntimeError as e:
    logging.error('Translation failed: %s; root cause: %s', e, e.__cause__)

Prevention

When it happens

Trigger: Applying a custom PTransform subclass without a registered URN in a cross-language or FnAPI context; transform.expand payload serialization failing; pickling failures for lambdas in transform specs.

Common situations: Portable/Flink/Spark runners requiring registered transforms; external transform misconfiguration; custom transforms using unpicklable closures.

Related errors

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