{"record":{"id":"6b914879831b171c","repo":"apache/iceberg","slug":"failed-to-deserialize-the-split","errorCode":null,"errorMessage":"Failed to deserialize the split.","messagePattern":"Failed to deserialize the split\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink/v1.20/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/v1.20/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplit.java#L113-L149","documentation":"IcebergSourceSplit.deserializeV1 uses Java serialization (InstantiationUtil.deserializeObject); if the class of the serialized object cannot be found on the classpath, it wraps ClassNotFoundException into RuntimeException. The split bytes reference classes unavailable at deserialization time.","triggerScenarios":"Restoring a checkpoint/savepoint or transferring split bytes where IcebergSourceSplit (or its referenced classes, e.g., the table/SerializableTable) is not on the TaskManager classpath, or was serialized by a different connector version with moved classes.","commonSituations":"Missing Iceberg jars on TaskManagers; shading conflicts relocating class packages; restoring state across connector versions with relocated classes.","solutions":["Ensure the iceberg-flink runtime jar is on every TaskManager's classpath (or bundled in the user job jar, not both partially).","Align connector versions between the job that created the checkpoint and the restoring job.","Check for shade/relocation mismatches (org.apache.iceberg classes relocated differently between builds).","Inspect the cause ClassNotFoundException for the exact missing class and add the dependency providing it."],"exampleFix":"// before\n# user jar contains iceberg classes shaded under different package than cluster lib\n// after\n# use consistent coordinates: bundle org.apache.iceberg:iceberg-flink-runtime same version in user jar only","handlingStrategy":"validation","validationCode":"// Verify the split classes resolve on the restoring cluster before submitting\nClass.forName(\"org.apache.iceberg.flink.source.split.IcebergSourceSplit\");\nClass.forName(\"org.apache.iceberg.SerializableTable\");","typeGuard":null,"tryCatchPattern":"try {\n  split = IcebergSourceSplitSerializer.INSTANCE.deserialize(version, bytes);\n} catch (RuntimeException e) {\n  if (e.getCause() instanceof ClassNotFoundException) {\n    throw new IllegalStateException(\"Iceberg classes missing on TaskManager classpath\", e);\n  }\n  throw e;\n}","preventionTips":["Bundle the full iceberg-flink-runtime jar in the user job jar","Keep the same connector version between checkpoint write and restore","Avoid inconsistent shade relocations of org.apache.iceberg packages","Check cause ClassNotFoundException to pinpoint missing dependency"],"tags":["flink","serialization","classpath","class-not-found"],"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"}