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 refuses to deserialize a split whose serialized format version is not 1, 2, or 3. The message text ("Supported version are [1]") is stale — the switch actually supports versions 1-3. This guard protects against reading splits written by incompatible Iceberg/Flink versions.

Source

Thrown at flink/v2.1/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 runtime jar version used by the Flink job with the version that wrote the checkpoint/savepoint
2. Restore from an older checkpoint/savepoint taken with a compatible version
3. Recreate the split enumerator state by starting the job without restore state
4. If the payload is suspected corrupt, re-ingest from the source rather than retrying

Example fix

// before
IcebergSourceSplit split = serializer.deserialize(version, bytes); // fails if version byte unknown
// after
// run the job with the Iceberg version matching the checkpoint, e.g. downgrade/upgrade flink iceberg jar

// Cannot inspect the version byte via public API reliably; ensure runtime matches the version that wrote the state:
// check org.apache.iceberg-flink runtime version against the checkpoint's Iceberg version before restore

try {
  split = serializer.deserialize(version, bytes);
} catch (IOException e) {
  if (e.getMessage().contains("unsupported version")) { /* restore from compatible checkpoint or drop state */ }
  throw e;
}

When it happens

Trigger: Deserializing an IcebergSourceSplit whose serialized byte payload carries a version byte outside [1,2,3] — e.g. splits written by a newer Iceberg version, corrupted checkpoint state, or a hand-modified payload.

Common situations: Restoring a Flink job from a checkpoint/savepoint produced with a different (newer) Iceberg version than the one on the classpath; rolling upgrades where JobManager and TaskManager jars differ; corrupt checkpoint bytes.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

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/896267e3711fb9b9. Report an issue: GitHub.