apache/beam · error · java.lang.IllegalArgumentException

Cannot convert unknown %s to %s: %s

Error message

Cannot convert unknown %s to %s: %s

What it means

PCollectionTranslation.fromProto converts the RunnerApi.IsBounded.Enum back to the Java IsBounded. UNRECOGNIZED or unhandled proto values (proto schema newer than the linked generated code) throw this IllegalArgumentException naming the source proto enum and value.

Source

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

        return RunnerApi.IsBounded.Enum.UNBOUNDED;
      default:
        throw new IllegalArgumentException(
            String.format("Unknown %s %s", IsBounded.class.getSimpleName(), bounded));
    }
  }

  static IsBounded fromProto(RunnerApi.IsBounded.Enum isBounded) {
    switch (isBounded) {
      case BOUNDED:
        return IsBounded.BOUNDED;
      case UNBOUNDED:
        return IsBounded.UNBOUNDED;
      case UNRECOGNIZED:
      default:
        // Whether or not this enum cannot be recognized by the proto (due to the version of the
        // generated code we link to) or the switch hasn't been updated to handle it,
        // the situation is the same: we don't know what this IsBounded means
        throw new IllegalArgumentException(
            String.format(
                "Cannot convert unknown %s to %s: %s",
                RunnerApi.IsBounded.class.getCanonicalName(),
                IsBounded.class.getCanonicalName(),
                isBounded));
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade the Beam SDK (and generated RunnerApi stubs) to a version that recognizes the incoming enum value.
2. Ensure all producers of pipeline protos use a compatible Beam version.
3. Inspect the pipeline proto to confirm the is_bounded field value is BOUNDED/UNBOUNDED.

Example fix

// before: older SDK parsing a newer proto
Pipeline p = Pipeline.fromProto(newerProto);
// after: upgrade dependency so enum values resolve
// pom.xml: <dependency><groupId>org.apache.beam</groupId><artifactId>beam-sdks-java-core</artifactId><version>x.y.z (>= producer version)</version></dependency>

// before deserializing a pipeline proto
if (proto.getComponents().getPcollectionsCount() > 0) { /* verify producer Beam version */ }

boolean isKnown(IsBounded.Enum v) { return v != null && v != IsBounded.Enum.UNRECOGNIZED; }

try { fromProto(enumValue); } catch (IllegalArgumentException e) { /* upgrade Beam SDK to recognize the enum */ throw e; }

When it happens

Trigger: fromProto (or isBounded, which calls it) receiving a RunnerApi.IsBounded.Enum of UNRECOGNIZED, e.g. a pipeline proto produced by a newer Beam version with an IsBounded value the current generated code cannot map.

Common situations: Deserializing pipeline protos from newer Beam SDKs/runner with an older SDK version; hand-crafted or mutated protos containing values outside the known enum set.

Related errors

• Unknown ValueKind number: {}
• Unknown %s %s
• Cannot convert unknown %s to %s: %s
• Unrecognized value for stable unique names:
• Unknown type

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