{"record":{"id":"c9a13c33ff1dcb56","repo":"apache/iceberg","slug":"failed-to-deserialize-the-split-c9a13c","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.2/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.2/flink/src/main/java/org/apache/iceberg/flink/source/split/IcebergSourceSplit.java#L113-L149","documentation":"IcebergSourceSplit.deserializeV1 uses Flink's Java-serialization fallback (InstantiationUtil.deserializeObject). If the bytes reference a class not on the classpath, ClassNotFoundException is wrapped in this RuntimeException.","triggerScenarios":"Deserializing a V1-encoded IcebergSourceSplit whose payload classes (e.g. TableSerializations, internal types) are missing from the task classloader.","commonSituations":"Shaded vs non-shaded connector mismatch on the Flink classpath; user-classloader isolation (parent-first/child-first) hiding Iceberg classes; mixed Iceberg versions between job and taskmanager classpath.","solutions":["Put the full iceberg-flink-runtime jar on the classpath consistently across JM and TM","Fix Flink classloading config (e.g. classloader.check-leaked-classloader, resolve-order) so user classes resolve","Ensure the same Iceberg version is used to serialize and deserialize","Prefer V2/V3 split serialization (table/scan JSON) which avoids Java serialization","If restoring old savepoints, ensure legacy classes referenced by V1 payloads are present"],"exampleFix":"// before: split jar with only iceberg-flink-runtime but core classes excluded\n// after: use full shaded runtime\n// org.apache.iceberg:iceberg-flink-runtime-1.19 (shaded, includes core)","handlingStrategy":"try-catch","validationCode":"// ensure the runtime jar is complete before reading state\nClass.forName(\"org.apache.iceberg.flink.source.split.IcebergSourceSplit\");","typeGuard":null,"tryCatchPattern":"try {\n  return IcebergSourceSplit.deserializeV1(bytes);\n} catch (RuntimeException e) {\n  if (e.getCause() instanceof ClassNotFoundException) {\n    throw new IllegalStateException(\"Iceberg classes missing from task classpath; check iceberg-flink-runtime jar\", e);\n  }\n  throw e;\n}","preventionTips":["Ship the full shaded iceberg-flink-runtime jar, not partial modules","Use identical Iceberg versions on JobManager and TaskManager classpaths","Prefer V2/V3 split serialization for new savepoints","Verify classloader resolve-order settings when using user classloaders"],"tags":["flink","deserialization","classpath","classnotfound"],"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"}