apache/iceberg · error · RuntimeException

Unknown serialize version:

Error message

Unknown serialize version: 

What it means

DeltaManifestsSerializer persists DeltaManifests (pending manifest files for a committable) into Flink checkpoint state. deserialize() accepts only the known VERSION_1 and VERSION_2 formats; any other version byte means the state was written by an incompatible (newer or corrupt) serializer, so it throws RuntimeException.

Source

Thrown at flink/v2.1/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 the job with the same (or newer) Iceberg version that wrote the checkpoint, then let it complete before downgrading.
2. Re-run the affected checkpoint interval without restore so fresh DeltaManifests are serialized with a known version.
3. Verify checkpoint storage integrity (object store/truncation issues) if corruption is suspected.
4. If downgrade is unavoidable, drain the pending commits via a successful checkpoint before switching versions.

try { restoreState(state); } catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unknown serialize version")) {
    LOG.error("Checkpoint written by incompatible Iceberg version; restart without this state or with matching version", e);
  }
}

When it happens

Trigger: Restoring a Flink job whose checkpoint/savepoint was written by a newer Iceberg version with an unimplemented serializer version, or checkpoint state bytes corrupted so the version int reads garbage.

Common situations: Downgrading the Iceberg Flink runtime after a checkpoint was taken with a newer version; restoring checkpoints across major version boundaries; truncated or corrupted checkpoint storage (e.g. HDFS/S3 issues).

Related errors

• Unrecognized version or corrupt state: <version>
• Unknown serialize version: ${version}
• Unrecognized version or corrupt state: ${version}
• 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/4b7e655a168a2007. Report an issue: GitHub.