apache/iceberg · critical · RuntimeException

Unknown serialize version: ${version}

Error message

Unknown serialize version: ${version}

What it means

DeltaManifestsSerializer.deserialize supports exactly two serialized-state versions (VERSION_1 and VERSION_2, used for manifest encoding of delta commits). If the checkpointed commit state carries any other version number, deserialization fails with a RuntimeException. This indicates state written by a different (usually newer) Iceberg version or corrupt version metadata.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/sink/DeltaManifestsSerializer.java:85

    out.write(deleteManifestBinary);

    CharSequence[] referencedDataFiles = deltaManifests.referencedDataFiles();
    out.writeInt(referencedDataFiles.length);
    for (CharSequence referencedDataFile : referencedDataFiles) {
      out.writeUTF(referencedDataFile.toString());
    }

    return binaryOut.toByteArray();
  }

  @Override
  public DeltaManifests deserialize(int version, byte[] serialized) throws IOException {
    if (version == VERSION_1) {
      return deserializeV1(serialized);
    } else if (version == VERSION_2) {
      return deserializeV2(serialized);
    } else {
      throw new RuntimeException("Unknown serialize version: " + version);
    }
  }

  private DeltaManifests deserializeV1(byte[] serialized) throws IOException {
    return new DeltaManifests(ManifestFiles.decode(serialized), null);
  }

  private DeltaManifests deserializeV2(byte[] serialized) throws IOException {
    ManifestFile dataManifest = null;
    ManifestFile deleteManifest = null;

    ByteArrayInputStream binaryIn = new ByteArrayInputStream(serialized);
    DataInputStream in = new DataInputStream(binaryIn);

    int dataManifestSize = in.readInt();
    if (dataManifestSize > 0) {
      byte[] dataManifestBinary = new byte[dataManifestSize];
      Preconditions.checkState(in.read(dataManifestBinary) == dataManifestSize);

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Restore with the same or newer Iceberg version that wrote the checkpoint; do not downgrade below the writer's format version.
2. Discard the incompatible checkpoint and start fresh (accepting a new snapshot for pending data).
3. Verify checkpoint integrity if corruption is suspected.

Example fix

// before
// running iceberg-flink-runtime 1.5 against checkpoints written by 1.6 with new version byte
bin/flink run -s cp-newer-version ...
// after
bin/flink run -s cp-newer-version --jarfile iceberg-flink-runtime-1.6.jar

// Check the checkpoint was written by the same or older Iceberg format version before restoring

try { manifests = DeltaManifestsSerializer.deserialize(version, bytes); } catch (RuntimeException e) { if (e.getMessage().startsWith("Unknown serialize version")) { LOG.error("Checkpoint from incompatible Iceberg version", e); throw e; } }

When it happens

Trigger: Restoring a Flink sink job whose two-phase-commit state contains DeltaManifests with a version byte not equal to 1 or 2, e.g. checkpoints written by a newer Iceberg release with a new format version.

Common situations: Downgrading Iceberg after checkpoints were written by a newer version; corrupted checkpoint bytes where the version field is invalid; manual state surgery.

Related errors

• Unrecognized version or corrupt state: ${version}
• Unrecognized version or corrupt state: ${version}
• Failed to deserialize IcebergSourceSplit. Encountered unsupp
• Unrecognized version or corrupt state: <version>
• Unrecognized version or corrupt state: ${version}

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