apache/iceberg · error · IOException

Unrecognized version or corrupt state:

Error message

Unrecognized version or corrupt state: 

What it means

IcebergCommittableSerializer.deserialize throws this IOException when the first byte (version marker) of a serialized IcebergCommittable does not match the current serializer version. It indicates the byte stream was written by an incompatible serializer version or the payload is truncated/corrupt.

Source

Thrown at flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/sink/IcebergCommittableSerializer.java:66

    view.writeInt(committable.manifest().length);
    view.write(committable.manifest());
    return out.toByteArray();
  }

  @Override
  public IcebergCommittable deserialize(int version, byte[] serialized) throws IOException {
    if (version == 1) {
      DataInputDeserializer view = new DataInputDeserializer(serialized);
      String jobId = view.readUTF();
      String operatorId = view.readUTF();
      long checkpointId = view.readLong();
      int manifestLen = view.readInt();
      byte[] manifestBuf;
      manifestBuf = new byte[manifestLen];
      view.read(manifestBuf);
      return new IcebergCommittable(manifestBuf, jobId, operatorId, checkpointId);
    }
    throw new IOException("Unrecognized version or corrupt state: " + version);
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Restore the job with the same Iceberg Flink runtime version that produced the savepoint/checkpoint
2. Start a new job without the incompatible savepoint state (accept re-processing of in-flight committables)
3. If corruption is suspected, re-run from an earlier healthy checkpoint and verify storage backend integrity

try {
  IcebergCommittable c = serializer.deserialize(version, view);
} catch (IOException e) {
  if (e.getMessage().startsWith("Unrecognized version")) {
    // fall back to previous serializer version or fail the restore with a clear upgrade message
  }
  throw e;
}

When it happens

Trigger: Deserializing an IcebergCommittable during Flink checkpoint/state recovery whose version byte differs from CURRENT_VERSION, or reading a corrupted/truncated state byte stream.

Common situations: Restoring a Flink savepoint/checkpoint taken with a different Iceberg version; upgraded connector reading old job state; Kafka/network corruption of serialized committables in exactly-once topologies.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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

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