{"record":{"id":"9d001dd78f71ba76","repo":"apache/iceberg","slug":"failed-to-deserialize-the-split-9d001d","errorCode":null,"errorMessage":"Failed to deserialize the split.","messagePattern":"Failed to deserialize the split\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplit.java","lineNumber":131,"sourceCode":"                        .add(\"length\", fileScanTask.length())\n                        .toString())\n            .collect(Collectors.toList()));\n  }\n\n  byte[] serializeV1() throws IOException {\n    if (serializedBytesCache == null) {\n      serializedBytesCache = InstantiationUtil.serializeObject(this);\n    }\n\n    return serializedBytesCache;\n  }\n\n  static IcebergSourceSplit deserializeV1(byte[] serialized) throws IOException {\n    try {\n      return InstantiationUtil.deserializeObject(\n          serialized, IcebergSourceSplit.class.getClassLoader());\n    } catch (ClassNotFoundException e) {\n      throw new RuntimeException(\"Failed to deserialize the split.\", e);\n    }\n  }\n\n  byte[] serializeV2() throws IOException {\n    return serialize(2);\n  }\n\n  byte[] serializeV3() throws IOException {\n    return serialize(3);\n  }\n\n  private byte[] serialize(int version) throws IOException {\n    if (serializedBytesCache == null) {\n      DataOutputSerializer out = SERIALIZER_CACHE.get();\n      Collection<FileScanTask> fileScanTasks = task.tasks();\n      Preconditions.checkArgument(\n          fileOffset >= 0 && fileOffset < fileScanTasks.size(),\n          \"Invalid file offset: %s. Should be within the range of [0, %s)\",","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/flink/v2.3/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplit.java#L113-L149","documentation":"deserializeV1 deserializes a version-1 serialized IcebergSourceSplit using Flink's InstantiationUtil Java serialization. If the bytes reference a class not present on the classpath, ClassNotFoundException is wrapped in this RuntimeException. It indicates the split state bytes cannot be reconstructed in the current runtime.","triggerScenarios":"Restoring a Flink savepoint/checkpoint whose operator state contains serialized splits referencing classes (e.g. old split or table classes) not found by the current classloader - typically after upgrading Iceberg or relocating/renaming classes.","commonSituations":"Upgrading the Iceberg version between a job stop-with-savepoint and resume; fat-jar shading issues where serializer classes are excluded; classloader isolation in Flink per-job/user-code classloaders.","solutions":["Use the same Iceberg version (or a compatible one) that wrote the savepoint when restoring.","If upgrade is required, let the old job finish or drain rather than restoring old split state into a new Iceberg version.","Verify the shaded jar contains all org.apache.iceberg.flink split classes (no class relocation mismatch).","Check Flink classloader settings (classloader.check-leaked-classloader, parent-first/child-first) if ClassNotFoundException appears only at runtime."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { split = IcebergSourceSplit.deserializeV1(bytes); } catch (RuntimeException e) { if (e.getCause() instanceof ClassNotFoundException) { throw new IllegalStateException('Savepoint written with a different Iceberg version; restore with matching version', e); } throw e; }","preventionTips":["Keep the Iceberg version stable between stop-with-savepoint and restore","Include all iceberg-flink classes in the job jar (verify shading/relocation)","Test savepoint/restore across your upgrade matrix before production upgrades","Avoid mixing Iceberg versions on the same Flink cluster classpath"],"tags":["flink","serialization","classpath","checkpoint"],"backgroundTag":"class-not-found","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"}