{"record":{"id":"3b99ebc7e7dbd7db","repo":"apache/iceberg","slug":"failed-to-deserialize-the-split-3b99eb","errorCode":null,"errorMessage":"Failed to deserialize the split.","messagePattern":"Failed to deserialize the split\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"flink/v2.1/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.1/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplit.java#L113-L149","documentation":"IcebergSourceSplit.deserializeV1 wraps a ClassNotFoundException thrown while Java-deserializing the split payload into RuntimeException with the message 'Failed to deserialize the split.' It means the split bytes were written by a class version not present on the deserializing task's classpath.","triggerScenarios":"deserializeV1 receives bytes whose embedded class can't be resolved against the task's classloader — e.g. restore with a different Iceberg flink-runtime jar, shaded-class relocation differences, or user-jar not shipped to all TaskManagers.","commonSituations":"Upgrading/downgrading the connector while resuming from savepoint; per-job vs lib deployment mismatch where the Iceberg jar exists on the JobManager but not TaskManagers; shade plugin relocated classes differently between versions.","solutions":["Deploy the identical iceberg-flink-runtime jar to all nodes and match the version that serialized the savepoint.","Ensure the jar is part of the user code (uber jar) rather than only on the JobManager classpath.","Verify shaded class relocation didn't change between versions; use the officially released flink-runtime artifact.","If recovery isn't possible, restart the job without state and let splits be re-planned."],"exampleFix":"// before: jar only on JM\nflink-conf classloader: parent-first with JM-only iceberg jar\n// after: ship jar with the job\nflink run -c Main job.jar // iceberg-flink-runtime bundled inside job.jar","handlingStrategy":"validation","validationCode":"// verify class availability in the task environment before restore\nClass.forName(\"org.apache.iceberg.flink.source.split.IcebergSourceSplit\",\n    true, Thread.currentThread().getContextClassLoader());","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Bundle iceberg-flink-runtime inside the user job jar so it ships to every TaskManager.","Keep connector versions identical to the checkpoint-writing version.","Verify shade relocations are stable across your custom builds.","Smoke-test savepoint restore in CI before production upgrades."],"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"}