apache/beam · error · java.lang.IllegalArgumentException

Unknown ValueKind: <valueKind>

Error message

Unknown ValueKind: <valueKind>

What it means

ValueKindUtil.toProto converts the in-memory ValueKind enum to its protobuf Elements.ValueKind.Enum; the default branch throws IllegalArgumentException when the enum has no proto mapping. This means a ValueKind value exists in memory that the toProto switch does not handle — usually a newer/older enum constant crossing SDK versions, or an unspecified value.

Source

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

 */
package org.apache.beam.sdk.values;

import org.apache.beam.model.fnexecution.v1.BeamFnApi.Elements;

/** Utility class for converting between {@link ValueKind} and {@link Elements.ValueKind.Enum}. */
public final class ValueKindUtil {
  public static Elements.ValueKind.Enum toProto(ValueKind valueKind) {
    switch (valueKind) {
      case INSERT:
        return Elements.ValueKind.Enum.INSERT;
      case UPDATE_BEFORE:
        return Elements.ValueKind.Enum.UPDATE_BEFORE;
      case UPDATE_AFTER:
        return Elements.ValueKind.Enum.UPDATE_AFTER;
      case DELETE:
        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. Only pass handled kinds (VALUE, UPDATE_BEFORE, UPDATE_AFTER, DELETE) to toProto
2. Upgrade Beam so toProto covers all enum constants present in your version
3. Map/guard unknown kinds before conversion (default to VALUE or reject earlier with a clear message)

Example fix

// before
Elements.ValueKind.Enum p = ValueKindUtil.toProto(kind); // kind may be arbitrary
// after
if (kind == ValueKind.VALUE || kind == ValueKind.UPDATE_BEFORE || kind == ValueKind.UPDATE_AFTER || kind == ValueKind.DELETE) { ... toProto ... } else { log.warn("skipping kind " + kind); }

if (kind != ValueKind.VALUE && kind != ValueKind.UPDATE_BEFORE && kind != ValueKind.UPDATE_AFTER && kind != ValueKind.DELETE) throw new IllegalArgumentException("unsupported kind: " + kind);

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

When it happens

Trigger: Calling ValueKindUtil.toProto(kind) where kind is not VALUE/UPDATE_BEFORE/UPDATE_AFTER/DELETE — e.g. VALUE_KIND_UNSPECIFIED passed in, or an enum constant added after this switch was written.

Common situations: Mixing Beam SDK versions where ValueKind gained constants; deserializing/mapping user-provided change-capture kinds; constructing ValueKind from strings and passing an unexpected value.

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: <proto>
• 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/a7b6e8ede6e15e65. Report an issue: GitHub.