apache/beam · error · java.lang.IllegalArgumentException

Unknown %s %s

Error message

Unknown %s %s

What it means

PCollectionTranslation.toProto converts a Java IsBounded to the protobuf enum. The switch handles BOUNDED and UNBOUNDED; anything else (i.e. a null or future-added value) reaches the default branch and throws this IllegalArgumentException.

Source

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

    return PCollection.createPrimitiveOutputInternal(
        pipeline,
        components.getWindowingStrategy(pCollection.getWindowingStrategyId()),
        fromProto(pCollection.getIsBounded()),
        (Coder) coder);
  }

  public static IsBounded isBounded(RunnerApi.PCollection pCollection) {
    return fromProto(pCollection.getIsBounded());
  }

  static RunnerApi.IsBounded.Enum toProto(IsBounded bounded) {
    switch (bounded) {
      case BOUNDED:
        return RunnerApi.IsBounded.Enum.BOUNDED;
      case UNBOUNDED:
        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",

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the PCollection was constructed normally so isBounded() is non-null.
2. Check for custom code or tests that stub IsBounded with unexpected values.
3. Update to a matching Beam version so the switch covers all IsBounded values.

Example fix

// before
IsBounded bounded = mockPcollection.isBounded(); // returns null
toProto(mockPcollection);
// after
checkArgument(mockPcollection.isBounded() != null, "isBounded must be set");
toProto(mockPcollection);

if (pcollection.isBounded() == null) throw new IllegalArgumentException("PCollection isBounded must be set");

null

try { toProto(pc); } catch (IllegalArgumentException e) { /* Unknown IsBounded — inspect pc construction */ throw e; }

When it happens

Trigger: Calling toProto(pcollection) (via PTransform translation) when pcollection.isBounded() returns a value not covered by the switch — in practice only null or a corrupted/extended IsBounded enum.

Common situations: Custom pipeline construction passing a null isBounded; reflective or mocked IsBounded values in tests; exotic IsBounded additions from a newer SDK mixed with older translation code.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Cannot convert unknown %s to %s: %s
• Transform with URN %s could not be translated
• Transform with URN %s failed to parse: %s
• Unrecognized value for stable unique names:
• Unknown ValueKind number: {}

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