apache/seatunnel · error · CheckpointStorageException

Failed to serialize checkpoint data

Error message

Failed to serialize checkpoint data

What it means

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.

Source

Thrown at seatunnel-engine/seatunnel-engine-storage/checkpoint-storage-plugins/checkpoint-storage-local-file/src/main/java/org/apache/seatunnel/engine/checkpoint/storage/localfile/LocalFileStorage.java:89

        }
    }

    /** set default storage root directory */
    private void setDefaultStorageSpaceByOSName() {
        if (System.getProperty("os.name").toLowerCase().contains("windows")) {
            setStorageNameSpace(DEFAULT_WINDOWS_OS_NAME_SPACE);
        } else {
            setStorageNameSpace(DEFAULT_LINUX_OS_NAME_SPACE);
        }
    }

    @Override
    public String storeCheckPoint(PipelineState state) throws CheckpointStorageException {
        byte[] datas;
        try {
            datas = serializeCheckPointData(state);
        } catch (IOException e) {
            throw new CheckpointStorageException("Failed to serialize checkpoint data", e);
        }
        // Consider file paths for different operating systems
        String fileName =
                getStorageParentDirectory()
                        + state.getJobId()
                        + File.separator
                        + getCheckPointName(state);

        File file = new File(fileName);
        try {
            FileUtils.touch(file);
        } catch (IOException e) {
            throw new CheckpointStorageException("Failed to create checkpoint file " + fileName, e);
        }

        try {
            FileUtils.writeByteArrayToFile(file, datas);
        } catch (IOException e) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Ensure all objects stored in the pipeline state (state map values) implement Serializable and their classes have stable serialVersionUID.
2. Upgrade/align SeaTunnel engine versions so serialization of state types is compatible.
3. Inspect the wrapped cause (getCause) for the concrete serialization error and fix the offending state entry.
4. Retry after fixing state contents; if it persists, report with the cause stacktrace.

Example fix

// before
state.putState(0, (Serializable) new SomeNonSerializableObject());
// after
state.putState(0, new SomeSerializableWrapper(someNonSerializableObject)); // implements Serializable

try {
    storage.storeCheckPoint(state);
} catch (CheckpointStorageException e) {
    if (e.getMessage().equals("Failed to serialize checkpoint data")) {
        log.error("Checkpoint serialization failed; inspect state contents", e.getCause());
    }
    throw e; // checkpoint failure must not be swallowed
}

When it happens

Trigger: 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.

Common situations: Custom plugins putting non-Serializable objects into checkpoint state; incompatible class versions between writer and reader; disk/stream errors during serialization.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• PACKET_DECODE_ERROR
• Failed to delete checkpoint directory
• Unsupported type in LocalTimeArrayType: ${eleSqlType}
• Unsupported type: ${sqlType}
• Unsupported type: ${clazz}

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/0815fe86133531c7. Report an issue: GitHub.