What causes "Transform with URN %s could not be translated" in apache/beam?

Check that all pipeline proto producers/consumers use compatible Beam versions.

apache/beam · error · java.lang.RuntimeException

Transform with URN %s could not be translated

Error message

Transform with URN %s could not be translated

What it means

The splittable-ParDo matcher in PTransformMatchers checks whether an applied ParDo transform is splittable by parsing its payload. If ParDoTranslation.isSplittable throws IOException during payload parsing, it is wrapped in this RuntimeException with the PAR_DO_TRANSFORM_URN, indicating the ParDo payload failed to parse.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/PTransformMatchers.java:274

      }
    };
  }

  /**
   * A {@link PTransformMatcher} that matches a {@link ParDo} by URN if it has a splittable {@link
   * DoFn}.
   */
  public static PTransformMatcher splittableParDo() {
    return new PTransformMatcher() {
      @Override
      public boolean matches(AppliedPTransform<?, ?, ?> application) {
        if (PTransformTranslation.PAR_DO_TRANSFORM_URN.equals(
            PTransformTranslation.urnForTransformOrNull(application.getTransform()))) {

          try {
            return ParDoTranslation.isSplittable(application);
          } catch (IOException e) {
            throw new RuntimeException(
                String.format(
                    "Transform with URN %s could not be translated",
                    PTransformTranslation.PAR_DO_TRANSFORM_URN),
                e);
          }
        }
        return false;
      }

      @Override
      public String toString() {
        return MoreObjects.toStringHelper("SplittableParDoMultiMatcher").toString();
      }
    };
  }

  /**
   * A {@link PTransformMatcher} that matches a {@link ParDo.SingleOutput} containing a {@link DoFn}

View on GitHub (pinned to 12126d8942)

Solutions

Check that all pipeline proto producers/consumers use compatible Beam versions.
Inspect the ParDo payload bytes for the failing transform and validate they decode as RunnerApi.ParDoPayload.
When editing this code, preserve the cause: pass `e` into the RuntimeException.

Example fix

// before
throw new RuntimeException(String.format("Transform with URN %s could not be translated", URN), e);
// after (debugging)
throw new RuntimeException(String.format("Transform with URN %s failed to parse ParDoPayload", URN), e);

Defensive patterns

Strategy: try-catch

Validate before calling

null

Try / catch

try { matcher.matches(application); } catch (RuntimeException e) { if (e.getCause() instanceof IOException) { /* ParDoPayload parse failure: check version skew */ } throw e; }

Prevention

Use a single Beam version across pipeline production and translation
Avoid mutating serialized ParDoPayload bytes
Verify payloads decode as RunnerApi.ParDoPayload in custom runners

When it happens

Trigger: A PTransformMatcher (splittable ParDo matching) runs over an AppliedPTransform whose ParDo payload bytes are malformed or incompatible — typically during pipeline optimization/translation when the proto was produced by a different Beam version.

Common situations: Version-skewed pipeline protos between stages; corrupt serialization of ParDo payloads; custom runners feeding unusual transform payloads into matchers.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

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