apache/iceberg · error · IOException

Unknown version:

Error message

Unknown version: 

What it means

IcebergEnumeratorStateSerializer.deserialize supports versions 1 and 2; any other version byte in serialized enumerator state throws IOException. The state was written by an incompatible connector version.

Source

Thrown at flink/v1.20/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. Restore with the same or newer connector version that produced the checkpoint.
2. Avoid downgrading across state-format changes; take a new savepoint with the target version while it is still running.
3. Start the job without state if the old state is unrecoverable, accepting reprocessing.

try {
  state = IcebergEnumeratorStateSerializer.deserialize(version, bytes);
} catch (IOException e) {
  LOG.warn("Incompatible enumerator state version; restarting without state", e);
  state = null;
}

When it happens

Trigger: Restoring a Flink checkpoint/savepoint whose enumerator state was serialized with a version other than 1 or 2 (e.g., newer connector's state read by an older connector).

Common situations: Downgrading the Iceberg Flink connector; cross-version state restore during job upgrade rollbacks.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Unknown version:
• Unknown serialize version:
• Unrecognized version or corrupt state: <version>
• Unknown serialize version: ${version}
• Unrecognized version or corrupt state: ${version}

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