apache/iceberg · error · IllegalArgumentException

Unknown read version: " + readVersion

Error message

Unknown read version: " + readVersion

What it means

SortKeySerializer's snapshot wrapper (readSnapshot) throws IllegalArgumentException when the serialized serializer-snapshot format version is neither 1 nor 2. The wrapper only knows how to restore versions 1 (readSnapshotPreamble) and 2 (read); a higher or unknown version means the bytes were written by a different Iceberg release.

Solutions

1. Restore the savepoint with an Iceberg version >= the one that wrote it (upgrade iceberg-flink-runtime, never downgrade past the writer's version).
2. Take a fresh savepoint with the target version, then stop the old-version state usage.
3. Verify no duplicate iceberg jars on the classpath causing the wrong snapshot reader to load.
4. If the version int looks absurd (huge/negative), treat the checkpoint as corrupted and restart from a fresh savepoint.

Example fix

// before: old jar reading v3 snapshot
// after: upgrade dependency
// implementation 'org.apache.iceberg:iceberg-flink-runtime-1.20:<matching-or-newer-version>'

try {
  snapshot.read(in);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException(
      "Serializer snapshot version newer than this Iceberg version; upgrade", e);
}

When it happens

Trigger: Restoring operator state whose SortKeySerializerSnapshot was written with an unknown version number — typically a savepoint/checkpoint from a newer Iceberg version being read by an older one, or corrupted state where the version int is wrong.

Common situations: Downgrading Iceberg after taking a savepoint; restoring a savepoint into a cluster with an older connector jar; byte corruption in checkpoint metadata.

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

• Could not deserialize the WriteResult object
• Fail to deserialize aggregated statistics,change to v1
• Fail to deserialize aggregated statistics,change to v1
• Fail to deserialize data statistics
• Failed to deserialize IcebergSourceSplit. Encountered…

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

Appendix: source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/sink/shuffle/SortKeySerializer.java:358

      Preconditions.checkState(sortOrder != null, "Invalid sort order: null");

      StringUtils.writeString(SchemaParser.toJson(schema), out);
      StringUtils.writeString(SortOrderParser.toJson(sortOrder), out);
    }

    @Override
    public void readSnapshot(int readVersion, DataInputView in, ClassLoader userCodeClassLoader)
        throws IOException {
      switch (readVersion) {
        case 1:
          read(in);
          this.version = 1;
          break;
        case 2:
          read(in);
          break;
        default:
          throw new IllegalArgumentException("Unknown read version: " + readVersion);
      }
    }

    @Override
    public TypeSerializerSchemaCompatibility<SortKey> resolveSchemaCompatibility(
        TypeSerializerSnapshot<SortKey> oldSerializerSnapshot) {
      if (!(oldSerializerSnapshot instanceof SortKeySerializerSnapshot)) {
        return TypeSerializerSchemaCompatibility.incompatible();
      }

      if (oldSerializerSnapshot.getCurrentVersion() == 1 && this.getCurrentVersion() == 2) {
        return TypeSerializerSchemaCompatibility.compatibleAfterMigration();
      }

      // Sort order should be identical
      SortKeySerializerSnapshot oldSnapshot = (SortKeySerializerSnapshot) oldSerializerSnapshot;
      if (!sortOrder.sameOrder(oldSnapshot.sortOrder)) {
        return TypeSerializerSchemaCompatibility.incompatible();

View on GitHub (pinned to 86d9c8fc54)