apache/iceberg · error · IOException

Unknown version:

Error message

Unknown version: 

What it means

IcebergEnumeratorStateSerializer.deserialize reads a version byte from the serialized enumerator state and dispatches to a known deserializer. This IOException is thrown when the version byte is not 1 or 2, meaning the state was written by an incompatible (newer or corrupt) serializer.

Source

Thrown at flink/v2.2/flink/src/main/java/org/apache/iceberg/flink/source/enumerator/IcebergEnumeratorStateSerializer.java:69

  @Override
  public int getVersion() {
    return VERSION;
  }

  @Override
  public byte[] serialize(IcebergEnumeratorState enumState) throws IOException {
    return serializeV2(enumState);
  }

  @Override
  public IcebergEnumeratorState deserialize(int version, byte[] serialized) throws IOException {
    switch (version) {
      case 1:
        return deserializeV1(serialized);
      case 2:
        return deserializeV2(serialized);
      default:
        throw new IOException("Unknown version: " + version);
    }
  }

  @VisibleForTesting
  byte[] serializeV1(IcebergEnumeratorState enumState) throws IOException {
    DataOutputSerializer out = SERIALIZER_CACHE.get();
    serializeEnumeratorPosition(out, enumState.lastEnumeratedPosition(), positionSerializer);
    serializePendingSplits(out, enumState.pendingSplits(), splitSerializer);
    byte[] result = out.getCopyOfBuffer();
    out.clear();
    return result;
  }

  @VisibleForTesting
  IcebergEnumeratorState deserializeV1(byte[] serialized) throws IOException {
    DataInputDeserializer in = new DataInputDeserializer(serialized);
    IcebergEnumeratorPosition enumeratorPosition =
        deserializeEnumeratorPosition(in, positionSerializer);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Use a connector version equal to or newer than the one that wrote the checkpoint/savepoint state
2. Verify the state byte[] actually came from IcebergEnumeratorStateSerializer.serialize (not another operator's state)
3. Restore from an older compatible savepoint/checkpoint
4. Inspect the first byte(s) of the serialized payload to confirm the version value

Example fix

// before: restoring new-version state with old connector
// flink-connector-iceberg 1.7 reading state serialized with version 3
// after: align versions
// implementation('org.apache.iceberg:iceberg-flink-runtime-1.19:1.10.0') // >= writing version

// before restore, verify state provenance
if (stateBytes == null || stateBytes.length == 0) {
  throw new IllegalStateException("Empty enumerator state; cannot restore");
}
// version byte is read first by the serializer; ensure it is 1 or 2

try {
  enumeratorState = IcebergEnumeratorStateSerializer.deserialize(stateVersion, stateBytes);
} catch (IOException e) {
  // fall back to a fresh enumeration or fail the job with a clear message
  throw new IllegalStateException("Incompatible enumerator state; recreate savepoint with matching connector version", e);
}

When it happens

Trigger: Restoring a Flink source enumerator from checkpoint/savepoint state whose version byte is greater than 2, or reading corrupted/random bytes as serializer input.

Common situations: Upgrading the Iceberg Flink connector after job state was written by a newer connector version; downgrading Flink/Iceberg versions so an old job cannot read new savepoints; corrupted checkpoint files.

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

• Failed to deserialize IcebergSourceSplit. Encountered unsupp
• Unknown version:
• Unsupported version:
• Unrecognized version or corrupt state:
• The Avro schema is not a nullable type: ${schema}

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/08600c4f0cd5b45c. Report an issue: GitHub.