apache/beam · error · CoderException

Unknown ValueKind number: {}

Error message

Unknown ValueKind number: {}

What it means

After reading the byte, ValueKindCoder maps it via Elements.ValueKind.Enum.forNumber; if no enum constant has that number, the byte is not a valid ValueKind and the coder throws CoderException naming the unknown number. This prevents silently producing a wrong kind from version skew or corrupt bytes.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/ValueKindCoder.java:63

  private ValueKindCoder() {}

  @Override
  public void encode(ValueKind value, OutputStream outStream) throws IOException, CoderException {
    if (value == null) {
      throw new CoderException("cannot encode a null ValueKind");
    }
    outStream.write(ValueKindUtil.toProto(value).getNumber());
  }

  @Override
  public ValueKind decode(InputStream inStream) throws IOException, CoderException {
    int number = inStream.read();
    if (number == -1) {
      throw new CoderException(new EOFException("EOF encountered decoding a ValueKind"));
    }
    Elements.ValueKind.@Nullable Enum proto = Elements.ValueKind.Enum.forNumber(number);
    if (proto == null) {
      throw new CoderException("Unknown ValueKind number: " + number);
    }

    return ValueKindUtil.fromProto(proto);
  }

  @Override
  public boolean consistentWithEquals() {
    return true;
  }

  @Override
  public boolean isRegisterByteSizeObserverCheap(ValueKind value) {
    return true;
  }

  @Override
  protected long getEncodedElementByteSize(ValueKind value) {
    return 1;

View on GitHub (pinned to 12126d8942)

Solutions

1. Align Beam SDK versions across writer and reader (same release for SDK and harness).
2. Validate the byte against Elements.ValueKind.Enum before decoding in custom pipelines.
3. Regenerate corrupted data; add transport checksums if corruption recurs.
4. Re-serialize data with one consistent version or add a migration decode path if enum numbering changed.

Example fix

// before
ValueKind k = kindCoder.decode(in); // may throw on unknown number
// after
int b = in.read();
if (Elements.ValueKind.Enum.forNumber(b) == null) {
  throw new IOException("Stream not produced by this Beam version; ValueKind byte " + b);
}
ValueKind k = kindCoder.decode(new ByteArrayInputStream(new byte[]{(byte) b}));

int b = in.read();
in.reset(); // where supported
if (Elements.ValueKind.Enum.forNumber(b) == null) {
  throw new IllegalArgumentException("Byte " + b + " is not a valid ValueKind enum number");
}

static boolean isValidValueKindByte(int b) {
  return Elements.ValueKind.Enum.forNumber(b) != null;
}

try {
  ValueKind k = kindCoder.decode(in);
} catch (CoderException e) {
  throw new VersionSkewException("Unknown ValueKind byte; check Beam SDK version skew", e);
}

When it happens

Trigger: Decoding a stream written by a different Beam version whose ValueKind enum numbering changed; corrupted bytes or a wrong-offset read of the single-byte field; hand-crafted test data with out-of-range enum numbers; a misaligned stream where a foreign byte lands at this position.

Common situations: Version skew between pipeline submission and runner/harness images; transport corruption; byte-stream misalignment after a prior element decoded the wrong length.

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

• Invalid encoded string length: {}
• error when decoding a textual integer
• EOF encountered decoding a ValueKind
• Unable to decode constant members from payload for ParamWind
• Unrecognized value for stable unique names:

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