apache/seatunnel · error · IMapStorageException

deserialize data error, class name is

Error message

deserialize data error, class name is {}

What it means

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.

Solutions

1. Install the plugin/jar versions that were in use when the WAL data was written.
2. Align the engine version used to read the storage with the version that wrote it, or migrate data with the old version first.
3. Check the exact class name in the message and add the corresponding jar to the classpath (plugins dir / lib).
4. If the data is disposable, wipe the storage directory and re-initialize.

Example fix

// before
// running new version against old WAL data -> ClassNotFoundException
// after
cp seatunnel-engine-old-classes.jar seatunnel/lib/ # or restore matching distribution version before loadAll

try { Object k = walReader.key(record); } catch (IMapStorageException e) { if (e.getCause() instanceof ClassNotFoundException) { /* install missing jar or use the writer's engine version */ } }

When it happens

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

Common situations: 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.

Related errors

• deserialize data error: data is s%, className is s%
• A deserialization failure event arrived
• can't support custom load jar
• CLASS_NOT_FOUND
• COMMON-02

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

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-storage/imap-storage-plugins/imap-storage-file/src/main/java/org/apache/seatunnel/engine/imap/storage/file/common/WALReader.java:128

            result.put(key, value);
        }
        return result;
    }

    private Object deserializeData(byte[] data, String className) {
        try {
            Class<?> clazz = ClassUtils.getClass(className);
            try {
                return serializer.deserialize(data, clazz);
            } catch (IOException e) {
                // log.error("deserialize data error, data is {}, className is {}", data, className,
                // e);
                throw new IMapStorageException(
                        e, "deserialize data error: data is s%, className is s%", data, className);
            }
        } catch (ClassNotFoundException e) {
            //  log.error("deserialize data error, class name is {}", className, e);
            throw new IMapStorageException(
                    e, "deserialize data error, class name is {}", className);
        }
    }
}

View on GitHub (pinned to cf67b549a7)