{"record":{"id":"1667e1eb402cc770","repo":"apache/seatunnel","slug":"deserialize-data-error-class-name-is","errorCode":null,"errorMessage":"deserialize data error, class name is {}","messagePattern":"deserialize data error, class name is (.+?)","errorType":"exception","errorClass":"IMapStorageException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-storage/imap-storage-plugins/imap-storage-file/src/main/java/org/apache/seatunnel/engine/imap/storage/file/common/WALReader.java","lineNumber":128,"sourceCode":"            result.put(key, value);\n        }\n        return result;\n    }\n\n    private Object deserializeData(byte[] data, String className) {\n        try {\n            Class<?> clazz = ClassUtils.getClass(className);\n            try {\n                return serializer.deserialize(data, clazz);\n            } catch (IOException e) {\n                // log.error(\"deserialize data error, data is {}, className is {}\", data, className,\n                // e);\n                throw new IMapStorageException(\n                        e, \"deserialize data error: data is s%, className is s%\", data, className);\n            }\n        } catch (ClassNotFoundException e) {\n            //  log.error(\"deserialize data error, class name is {}\", className, e);\n            throw new IMapStorageException(\n                    e, \"deserialize data error, class name is {}\", className);\n        }\n    }\n}\n","sourceCodeStart":110,"sourceCodeEnd":133,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-storage/imap-storage-plugins/imap-storage-file/src/main/java/org/apache/seatunnel/engine/imap/storage/file/common/WALReader.java#L110-L133","documentation":"WALReader.deserializeData could not load the class named in the WAL record: ClassUtils.getClass(className) threw ClassNotFoundException. The stored record references a Java class not present on the current classpath, so key()/value() cannot materialize it.","triggerScenarios":"Calling WALReader key()/value() on data written by a SeaTunnel version (or plugin) whose classes were later renamed/moved/shaded; running a slim distribution missing plugin jars that were present when the data was written.","commonSituations":"SeaTunnel upgrade where internal classes moved packages; cluster reading WAL data written with third-party plugin jars not installed in the new deployment; shaded class relocation changes.","solutions":["Install the plugin/jar versions that were in use when the WAL data was written.","Align the engine version used to read the storage with the version that wrote it, or migrate data with the old version first.","Check the exact class name in the message and add the corresponding jar to the classpath (plugins dir / lib).","If the data is disposable, wipe the storage directory and re-initialize."],"exampleFix":"// before\n// running new version against old WAL data -> ClassNotFoundException\n// after\ncp seatunnel-engine-old-classes.jar seatunnel/lib/ # or restore matching distribution version before loadAll","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { Object k = walReader.key(record); } catch (IMapStorageException e) { if (e.getCause() instanceof ClassNotFoundException) { /* install missing jar or use the writer's engine version */ } }","preventionTips":["Install all plugin jars that existed when the WAL data was written before running recovery","Avoid reusing old storage directories after class/package renames in upgrades","Keep the distribution that wrote the data available for migration"],"tags":["classpath","deserialization","class-not-found","wal"],"backgroundTag":"class-not-found","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}