apache/iceberg · error · IOException

Unknown version: {version}

Error message

Unknown version: {version}

What it means

IcebergEnumeratorStateSerializer.deserialize throws IOException when the enumerator-state blob's version byte is neither 1 nor 2, i.e. state written by an incompatible connector version. It protects readers from decoding state layouts they don't understand.

Source

Thrown at flink/v2.1/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. Restart the restore using the connector version that matches the state's writer version (same or newer).
2. Start fresh (no savepoint) and let the enumerator re-enumerate from the table if state migration isn't feasible.
3. Use Flink state-processor-api to inspect/rewrite the enumerator state to a supported version.
4. Align all jars in the deployment so writer and reader versions can never diverge.

Example fix

// before
env.execute with connector 1.8.x restoring state written by 1.10.x
// after
upgrade job to iceberg-flink-runtime 1.10.x before restoring the savepoint

// ensure deployment jars match before resuming
Preconditions.checkState(
    IcebergBuild.version().equals(stateWritingIcebergVersion),
    "Connector version mismatch with checkpoint state");

When it happens

Trigger: Restoring from a checkpoint/savepoint whose IcebergEnumeratorState bytes were serialized with a version outside {1,2}, typically by a newer connector release.

Common situations: Rolling upgrade where the job manager restored state produced by a newer flink-runtime jar; downgrading the connector; cross-version state migration between Flink 1.x streams.

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: {version}
• Unknown version:
• Unknown version:
• Unsupported version:
• Unsupported version: {version}

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