{"record":{"id":"d7e948909a738776","repo":"apache/iceberg","slug":"failed-to-deserialize-icebergsourcesplit-encounte-d7e948","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.3/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.3/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplitSerializer.java#L38-L65","documentation":"IcebergSourceSplitSerializer.deserialize reads the version byte of a serialized split and dispatches to deserializeV1/V2/V3. Any other version (including 0 or versions from a newer Iceberg) throws an IOException stating the unsupported version and listing [1] (message text is slightly stale since 2 and 3 are also supported).","triggerScenarios":"A split serializer instance configured with an older SIMPLE_VERSION (deserialize path gated by version 1) reads bytes whose version byte is 2 or 3, or bytes written by a newer Iceberg with an unknown version, during checkpoint/split-state recovery.","commonSituations":"Downgrading iceberg-flink between job stop and restore; savepoints shared across clusters with different Iceberg versions; manually crafted/edited split bytes.","solutions":["Restore the job with the same or newer iceberg-flink version that wrote the split state.","Set the serializer version consistently (IcebergSourceOptions.SPLIT_SERIALIZER_VERSION / simple vs versioned serializer) so writer and reader agree.","If downgrade is unavoidable, run the old job to completion or use a compatibility version that can read the existing split format.","Report/patch the stale '[1]' message if it misleads your debugging; versions 2 and 3 are supported."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// inspect first byte of serialized split before deserializing\nint version = serialized[0];\nif (version < 1 || version > 3) throw new IOException('split version ' + version + ' unreadable by this Iceberg version');","typeGuard":null,"tryCatchPattern":"try { split = serializer.deserialize(version, bytes); } catch (IOException e) { if (e.getMessage().contains('unsupported version')) { throw new IllegalStateException('Restore with the Iceberg version that wrote the checkpoint', e); } throw e; }","preventionTips":["Match SPLIT_SERIALIZER_VERSION across writer and reader","Never downgrade iceberg-flink across a savepoint/restore boundary","Note the error message is stale: versions 2 and 3 are supported; check the actual version byte"],"tags":["flink","serialization","versioning","checkpoint"],"backgroundTag":"unsupported-enum-value","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"}