{"record":{"id":"0815fe86133531c7","repo":"apache/seatunnel","slug":"failed-to-serialize-checkpoint-data","errorCode":null,"errorMessage":"Failed to serialize checkpoint data","messagePattern":"Failed to serialize checkpoint data","errorType":"exception","errorClass":"CheckpointStorageException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-local-file/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/localfile/LocalFileStorage.java","lineNumber":89,"sourceCode":"        }\n    }\n\n    /** set default storage root directory */\n    private void setDefaultStorageSpaceByOSName() {\n        if (System.getProperty(\"os.name\").toLowerCase().contains(\"windows\")) {\n            setStorageNameSpace(DEFAULT_WINDOWS_OS_NAME_SPACE);\n        } else {\n            setStorageNameSpace(DEFAULT_LINUX_OS_NAME_SPACE);\n        }\n    }\n\n    @Override\n    public String storeCheckPoint(PipelineState state) throws CheckpointStorageException {\n        byte[] datas;\n        try {\n            datas = serializeCheckPointData(state);\n        } catch (IOException e) {\n            throw new CheckpointStorageException(\"Failed to serialize checkpoint data\", e);\n        }\n        // Consider file paths for different operating systems\n        String fileName =\n                getStorageParentDirectory()\n                        + state.getJobId()\n                        + File.separator\n                        + getCheckPointName(state);\n\n        File file = new File(fileName);\n        try {\n            FileUtils.touch(file);\n        } catch (IOException e) {\n            throw new CheckpointStorageException(\"Failed to create checkpoint file \" + fileName, e);\n        }\n\n        try {\n            FileUtils.writeByteArrayToFile(file, datas);\n        } catch (IOException e) {","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-local-file/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/localfile/LocalFileStorage.java#L71-L107","documentation":"LocalFileStorage.storeCheckPoint serializes the PipelineState to bytes before persisting it to the local filesystem; an IOException from the serializer is wrapped in CheckpointStorageException. This happens before any file is written, so the failure is purely in serialization of the checkpoint state.","triggerScenarios":"Calling storeCheckPoint(state) when the Java object serialization of PipelineState or its nested state maps fails — e.g. non-serializable objects placed in state, or an underlying stream/IO error during serialization.","commonSituations":"Custom plugins putting non-Serializable objects into checkpoint state; incompatible class versions between writer and reader; disk/stream errors during serialization.","solutions":["Ensure all objects stored in the pipeline state (state map values) implement Serializable and their classes have stable serialVersionUID.","Upgrade/align SeaTunnel engine versions so serialization of state types is compatible.","Inspect the wrapped cause (getCause) for the concrete serialization error and fix the offending state entry.","Retry after fixing state contents; if it persists, report with the cause stacktrace."],"exampleFix":"// before\nstate.putState(0, (Serializable) new SomeNonSerializableObject());\n// after\nstate.putState(0, new SomeSerializableWrapper(someNonSerializableObject)); // implements Serializable","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    storage.storeCheckPoint(state);\n} catch (CheckpointStorageException e) {\n    if (e.getMessage().equals(\"Failed to serialize checkpoint data\")) {\n        log.error(\"Checkpoint serialization failed; inspect state contents\", e.getCause());\n    }\n    throw e; // checkpoint failure must not be swallowed\n}","preventionTips":["Only put Serializable objects with fixed serialVersionUID into checkpoint state.","Avoid storing engine/plugin-internal mutable objects in the state map.","Pin engine and plugin versions so state classes stay serialization-compatible."],"tags":["serialization","checkpoint","local-file"],"backgroundTag":"json-marshal-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}