apache/iceberg · error · IOException

Failed to deserialize IcebergSourceSplit. Encountered unsupp

Error message

Failed to deserialize IcebergSourceSplit. Encountered unsupported version: %d. Supported version are [1]

What it means

IcebergSourceSplitSerializer.deserialize only supports serialized split versions 1-3 (dispatching to deserializeV1/V2/V3). Any other version byte throws an IOException. This is the top-level guard against split state written by an incompatible connector version.

Source

Thrown at flink/v1.20/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplitSerializer.java:56

    return VERSION;
  }

  @Override
  public byte[] serialize(IcebergSourceSplit split) throws IOException {
    return split.serializeV3();
  }

  @Override
  public IcebergSourceSplit deserialize(int version, byte[] serialized) throws IOException {
    switch (version) {
      case 1:
        return IcebergSourceSplit.deserializeV1(serialized);
      case 2:
        return IcebergSourceSplit.deserializeV2(serialized, caseSensitive);
      case 3:
        return IcebergSourceSplit.deserializeV3(serialized, caseSensitive);
      default:
        throw new IOException(
            String.format(
                Locale.ROOT,
                "Failed to deserialize IcebergSourceSplit. "
                    + "Encountered unsupported version: %d. Supported version are [1]",
                version));
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Align the iceberg-flink-runtime jar version with the one that produced the savepoint/checkpoint
2. Upgrade all nodes to a connector version that supports the serialized version found
3. Discard the savepoint and start a new job (letting the enumerator re-plan splits)
4. Verify only one iceberg-flink-runtime version is on the classpath

try {
  IcebergSourceSplit split = serializer.deserialize(version, serialized);
} catch (IOException e) {
  // treat as incompatible state: discard and let the enumerator re-plan
  LOG.warn("Unsupported split version {}; re-planning splits", version, e);
}

When it happens

Trigger: Calling deserialize (via the SimpleVersionedSerializer used by the Flink split enumerator) on bytes whose version header is not 1, 2, or 3 — typically state from a newer or older iceberg-flink-runtime.

Common situations: Flink job restore across Iceberg connector major upgrades; mismatched iceberg-flink-runtime jars on JobManager vs TaskManagers; hand-edited or corrupted checkpoint metadata.

Related errors

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

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