apache/beam · error · java.lang.IllegalStateException

No translator known for %s

Error message

No translator known for %s

What it means

PTransformTranslation.urnForTransform resolves the URN for a PTransform via registered payload translators; urnForTransformOrNull returns null when no registered translator supports the transform class. This IllegalStateException then reports that no translator is known for the given class name.

Source

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

    return tag.getId();
  }

  /** Returns the URN for the transform if it is known, otherwise {@code null}. */
  public static @Nullable String urnForTransformOrNull(PTransform<?, ?> transform) {
    TransformTranslator<?> transformTranslator =
        Iterables.find(
            KNOWN_TRANSLATORS,
            translator -> translator.canTranslate(transform),
            DefaultUnknownTransformTranslator.INSTANCE);
    return ((TransformTranslator) transformTranslator).getUrn(transform);
  }

  /** Returns the URN for the transform if it is known, otherwise throws. */
  public static String urnForTransform(PTransform<?, ?> transform) {
    String urn = urnForTransformOrNull(transform);

    if (urn == null) {
      throw new IllegalStateException(
          String.format("No translator known for %s", transform.getClass().getName()));
    }
    return urn;
  }

  /** Returns the URN for the transform if it is known, otherwise {@code null}. */
  public static @Nullable String urnForTransformOrNull(RunnerApi.PTransform transform) {
    return transform.getSpec() == null ? null : transform.getSpec().getUrn();
  }

  /**
   * A translator between a Java-based {@link PTransform} and a protobuf for that transform.
   *
   * <p>When going to a protocol buffer message, the translator produces a payload corresponding to
   * the Java representation while registering components that transform references.
   */
  public interface TransformTranslator<T extends PTransform<?, ?>> {
    @Nullable String getUrn(T transform);

View on GitHub (pinned to 12126d8942)

Solutions

1. Register a payload translator for the custom transform class (extend PTransformTranslation.PTransformPayloadTranslator and register it via ServiceLoader or the appropriate registry).
2. Replace the unknown transform with an expandable composite of built-in transforms (ParDo, GroupByKey, etc.) so no custom URN is needed.
3. Check META-INF/services/org.apache.beam.sdk.transforms.reflect.PTransformTranslator (or equivalent) is intact in the classpath; fix shading config.
4. Use urnForTransformOrNull if you only need a nullable lookup instead of a throw.

Example fix

// before
apply(new MyCustomTransform()); // IllegalStateException: No translator known for ...
// after
@AutoService(PTransformPayloadTranslator.class)
class MyCustomTransformTranslator implements PTransformPayloadTranslator<MyCustomTransform> { ... }

if (PTransformTranslation.urnForTransformOrNull(transform) == null) { throw new IllegalStateException("Register a translator for " + transform.getClass().getName()); }

boolean translatable(PTransform<?, ?> t) { return PTransformTranslation.urnForTransformOrNull(t) != null; }

try { String urn = PTransformTranslation.urnForTransform(transform); } catch (IllegalStateException e) { /* register translator or replace transform */ throw e; }

When it happens

Trigger: Calling urnForTransform (directly or via pipeline translation) with a custom PTransform subclass that has no registered PTransformTranslator/PTransformPayloadTranslator, or with a built-in transform whose translator ServiceLoader entry is missing from the classpath.

Common situations: Custom composite/leaf transforms used without a custom translator registration (WriteableTransform registries); shaded jars dropping META-INF/services registrations; passing a plain DoFn-wrapped custom transform where Impulse/ParDo expansion is expected.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• cannot register Coder : does not have an accessible method n
• cannot register Coder : method named 'of' with arguments of
• Unknown %s %s
• Transform with URN %s could not be translated
• Transform with URN %s failed to parse: %s

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