apache/beam · error · RuntimeException

Internal error determining boundedness of Read

Error message

Internal error determining boundedness of Read

What it means

ReadTranslation.sourceIsBounded() determines whether a Read transform's source is bounded by round-tripping the transform to its proto form (PTransformTranslation.toProto), parsing the payload back with ReadPayload.parseFrom, and reading isBounded. Any IOException during this serialize/parse round trip is wrapped in a RuntimeException labeled 'Internal error determining boundedness of Read'. By design this path should never fail for a well-formed Read transform, so it signals an internal invariant violation.

Source

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

  public static UnboundedSource<?, ?> unboundedSourceFromProto(ReadPayload payload) {
    checkArgument(payload.getIsBounded().equals(IsBounded.Enum.UNBOUNDED));
    return (UnboundedSource<?, ?>)
        SerializableUtils.deserializeFromByteArray(
            payload.getSource().getPayload().toByteArray(), "UnboundedSource");
  }

  public static PCollection.IsBounded sourceIsBounded(AppliedPTransform<?, ?, ?> transform) {
    try {
      SdkComponents components = SdkComponents.create(transform.getPipeline().getOptions());
      return PCollectionTranslation.fromProto(
          ReadPayload.parseFrom(
                  PTransformTranslation.toProto(transform, Collections.emptyList(), components)
                      .getSpec()
                      .getPayload())
              .getIsBounded());
    } catch (IOException e) {
      throw new RuntimeException("Internal error determining boundedness of Read", e);
    }
  }

  /**
   * A {@link PTransformTranslation.TransformPayloadTranslator} for {@link
   * SplittableParDo.PrimitiveUnboundedRead}.
   */
  public static class UnboundedReadPayloadTranslator
      implements PTransformTranslation.TransformPayloadTranslator<
          SplittableParDo.PrimitiveUnboundedRead<?>> {
    public static PTransformTranslation.TransformPayloadTranslator create() {
      return new UnboundedReadPayloadTranslator();
    }

    private UnboundedReadPayloadTranslator() {}

    @Override
    public String getUrn() {

View on GitHub (pinned to 12126d8942)

Solutions

Inspect the wrapped IOException cause to see which stage (toProto vs parseFrom) failed.
Verify the PTransform is a genuine Read transform with a valid ReadPayload spec.
Remove or fix custom TransformPayloadTranslator registrations that override Read translation.
Ensure all Beam SDK/runner modules use the same version to avoid proto schema skew.

Example fix

// before
boolean bounded = ReadTranslation.sourceIsBounded(readTransform, components);
// after
try {
  boolean bounded = ReadTranslation.sourceIsBounded(readTransform, components);
} catch (RuntimeException e) {
  throw new IllegalStateException("Transform is not a translatable Read: " + readTransform.getKindString(), e);
}

Defensive patterns

Strategy: try-catch

Try / catch

try { boolean b = ReadTranslation.sourceIsBounded(t, components); } catch (RuntimeException e) { throw new IllegalStateException("Not a translatable Read transform", e); }

Prevention

Only pass genuine Read transforms to sourceIsBounded
Keep all Beam modules on one version
Avoid overriding Read's payload translator

When it happens

Trigger: Calling ReadTranslation.sourceIsBounded(transform, components) where PTransformTranslation.toProto(...) or ReadPayload.parseFrom(...) throws IOException — typically a Read transform whose spec payload is missing, corrupted, or not a ReadPayload (e.g. a custom/overridden Read-like transform registered incorrectly).

Common situations: Custom PTransform payload translators interfering with Read translation, corrupted or hand-built pipeline protos, or version skew between SDK components producing an unexpected transform spec payload.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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