{"record":{"id":"896267e3711fb9b9","repo":"apache/iceberg","slug":"failed-to-deserialize-icebergsourcesplit-encounte-896267","errorCode":null,"errorMessage":"Failed to deserialize IcebergSourceSplit. Encountered unsupported version: %d. Supported version are [1]","messagePattern":"Failed to deserialize IcebergSourceSplit\\. Encountered unsupported version: (.+?)\\. Supported version are \\[1\\]","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplitSerializer.java","lineNumber":56,"sourceCode":"    return VERSION;\n  }\n\n  @Override\n  public byte[] serialize(IcebergSourceSplit split) throws IOException {\n    return split.serializeV3();\n  }\n\n  @Override\n  public IcebergSourceSplit deserialize(int version, byte[] serialized) throws IOException {\n    switch (version) {\n      case 1:\n        return IcebergSourceSplit.deserializeV1(serialized);\n      case 2:\n        return IcebergSourceSplit.deserializeV2(serialized, caseSensitive);\n      case 3:\n        return IcebergSourceSplit.deserializeV3(serialized, caseSensitive);\n      default:\n        throw new IOException(\n            String.format(\n                Locale.ROOT,\n                \"Failed to deserialize IcebergSourceSplit. \"\n                    + \"Encountered unsupported version: %d. Supported version are [1]\",\n                version));\n    }\n  }\n}\n","sourceCodeStart":38,"sourceCodeEnd":65,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.1/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplitSerializer.java#L38-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Align the Iceberg runtime jar version used by the Flink job with the version that wrote the checkpoint/savepoint","Restore from an older checkpoint/savepoint taken with a compatible version","Recreate the split enumerator state by starting the job without restore state","If the payload is suspected corrupt, re-ingest from the source rather than retrying"],"exampleFix":"// before\nIcebergSourceSplit split = serializer.deserialize(version, bytes); // fails if version byte unknown\n// after\n// run the job with the Iceberg version matching the checkpoint, e.g. downgrade/upgrade flink iceberg jar","handlingStrategy":"try-catch","validationCode":"// Cannot inspect the version byte via public API reliably; ensure runtime matches the version that wrote the state:\n// check org.apache.iceberg-flink runtime version against the checkpoint's Iceberg version before restore","typeGuard":null,"tryCatchPattern":"try {\n  split = serializer.deserialize(version, bytes);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"unsupported version\")) { /* restore from compatible checkpoint or drop state */ }\n  throw e;\n}","preventionTips":["Pin the same Iceberg Flink runtime jar version across JobManager/TaskManagers and all releases","Avoid modifying serialized split payloads; keep checkpoints from one writer version","Test savepoint restore across version upgrades before production rollovers"],"tags":["flink","serialization","checkpoint","version-compatibility"],"backgroundTag":"incompatible-source-type","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}