apache/beam · error · java.lang.IllegalArgumentException

Unknown ValueKind: <proto>

Error message

Unknown ValueKind: <proto>

What it means

ValueKindUtil.fromProto converts a protobuf Elements.ValueKind.Enum back to the in-memory ValueKind; the default branch throws IllegalArgumentException when the proto enum value has no mapping. This occurs for VALUE_KIND_UNSPECIFIED or proto constants the installed SDK's switch does not know (version skew between writer and reader).

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/values/ValueKindUtil.java:51

        return Elements.ValueKind.Enum.DELETE;
      default:
        throw new IllegalArgumentException("Unknown ValueKind: " + valueKind);
    }
  }

  public static ValueKind fromProto(Elements.ValueKind.Enum proto) {
    switch (proto) {
      case VALUE_KIND_UNSPECIFIED:
      case INSERT:
        return ValueKind.INSERT;
      case UPDATE_BEFORE:
        return ValueKind.UPDATE_BEFORE;
      case UPDATE_AFTER:
        return ValueKind.UPDATE_AFTER;
      case DELETE:
        return ValueKind.DELETE;
      default:
        throw new IllegalArgumentException("Unknown ValueKind: " + proto);
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade the Beam SDK so fromProto handles all proto constants your data may contain
2. Handle VALUE_KIND_UNSPECIFIED upstream (skip or default) before calling fromProto
3. Regenerate/normalize protos with a matching Beam version instead of mixing versions

Example fix

// before
ValueKind k = ValueKindUtil.fromProto(proto); // proto == VALUE_KIND_UNSPECIFIED
// after
ValueKind k = (proto == Elements.ValueKind.Enum.VALUE_KIND_UNSPECIFIED) ? ValueKind.VALUE : ValueKindUtil.fromProto(proto);

if (proto == Elements.ValueKind.Enum.VALUE_KIND_UNSPECIFIED) { proto = Elements.ValueKind.Enum.VALUE; }

try { kind = ValueKindUtil.fromProto(proto); } catch (IllegalArgumentException e) { log.warn("unknown proto kind", e); kind = ValueKind.VALUE; }

When it happens

Trigger: Calling ValueKindUtil.fromProto(proto) with VALUE_KIND_UNSPECIFIED, or with a proto constant added by a newer Beam version than the one running this switch.

Common situations: Reading pipeline graph/Elements protos produced by a different Beam version; protos serialized with unspecified kind fields; hand-crafted protos in tests.

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

• Unknown ValueKind: <valueKind>
• Unknown DirectoryTreatment: " + directoryTreatment
• Failed to decode Schema due to an error decoding Field proto
• Encountered UNSPECIFIED AtomicType
• Encountered unknown AtomicType: +protoFieldType.getAtomicTyp

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