apache/iceberg · error · IllegalArgumentException

Unknown read version: ${readVersion}

Error message

Unknown read version: ${readVersion}

What it means

SortKeySerializer's snapshot read (SortKeySerializerSnapshot.readSnapshot) deserializes a version marker from the checkpoint stream; only versions 1 and 2 are known. If the marker is anything else, the version byte is corrupt or was written by a newer Iceberg/Flink release, so it throws IllegalArgumentException "Unknown read version".

Source

Thrown at flink/v2.1/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)

Solutions

1. Align the iceberg-flink-runtime version of the restoring job with (or be newer than) the version that wrote the savepoint.
2. If a downgrade is required, start the job from a fresh checkpoint/savepoint taken with the target version instead of restoring old state.
3. Discard the incompatible state and let the sink re-initialize sort-key statistics (acceptable since they are advisory for data distribution).

Example fix

// before
<dependency>org.apache.iceberg:iceberg-flink-runtime-1.19:1.6.0</dependency> // wrote v2 snapshot, then downgraded
// after: keep runtime version >= writer version across restarts
<dependency>org.apache.iceberg:iceberg-flink-runtime-1.19:1.9.0</dependency>

// No pre-call check; verify state provenance before restore
// Ensure the runtime version that wrote the savepoint <= current runtime version

try {
  restoreFrom(savepoint);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Unknown read version")) {
    // start without state or with a savepoint from a compatible version
  }
}

When it happens

Trigger: Reading a savepoint/checkpoint whose serialized SortKeySerializerSnapshot contains a version code other than 1 or 2 — typically restoring a job written by a newer Iceberg version into a job running an older version.

Common situations: Downgrading the iceberg-flink-runtime version between job restarts; corrupted or hand-edited savepoint metadata; attempting cross-version state compatibility with a build that introduced a new serializer version.

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

• Unknown read version:
• Failed to deserialize IcebergSourceSplit. Encountered unsupp
• Unknown serialize version:
• Unrecognized version or corrupt state: ${version}
• Failed to deserialize IcebergSourceSplit. Encountered unsupp

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