apache/flink · critical · IllegalStateException

Unrecognized Kryo registration serializer definition type: {

Error message

Unrecognized Kryo registration serializer definition type: {}

What it means

The read-side counterpart of the Kryo registration serializer-definition switch in KryoSerializerSnapshotData.tryReadKryoRegistration: after reading the tag byte it dispatches on CLASS or INSTANCE; any other value means the snapshot data is invalid (corrupt checkpoint or a format this Flink version cannot parse) and an IllegalStateException is thrown naming the unrecognized type.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/java/typeutils/runtime/kryo/KryoSerializerSnapshotData.java:300

            switch (serializerDefinitionType) {
                case UNSPECIFIED:
                    {
                        return new KryoRegistration(registeredClass);
                    }
                case CLASS:
                    {
                        return tryReadWithSerializerClass(
                                in, userCodeClassLoader, registeredClassname, registeredClass);
                    }
                case INSTANCE:
                    {
                        return tryReadWithSerializerInstance(
                                in, userCodeClassLoader, registeredClassname, registeredClass);
                    }
                default:
                    {
                        throw new IllegalStateException(
                                "Unrecognized Kryo registration serializer definition type: "
                                        + serializerDefinitionType);
                    }
            }
        }

        @SuppressWarnings("unchecked")
        private static KryoRegistration tryReadWithSerializerClass(
                DataInputView in,
                ClassLoader userCodeClassLoader,
                String registeredClassname,
                Class<?> registeredClass)
                throws IOException {
            String serializerClassname = in.readUTF();
            Class serializerClass;
            try {
                serializerClass = Class.forName(serializerClassname, true, userCodeClassLoader);
                return new KryoRegistration(registeredClass, serializerClass);

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Verify the checkpoint/savepoint file integrity (size, checksum, completeness) and re-upload or pick an intact one.
2. Restore with the same Flink version that wrote the checkpoint before attempting any upgrade.
3. Follow the documented savepoint compatibility path (same version restore -> upgrade -> new version) rather than jumping versions.
4. If the state is expendable, restart without restore; otherwise use the state processor API to inspect what is readable.

// Before restoring, verify the savepoint metadata is complete/readable.
try (DataInputStream in = new DataInputStream(new FileInputStream(metaFile))) {
    in.readByte(); // any early read failure => truncated file
} catch (IOException e) {
    throw new IllegalStateException("Checkpoint metadata unreadable: " + metaFile, e);
}

try {
    env.restoreStateFromSavepoint(savepointPath);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Unrecognized Kryo registration")) {
        // corrupt or incompatible checkpoint: pick intact savepoint / same Flink version
    }
    throw e;
}

When it happens

Trigger: Restoring a checkpoint/savepoint whose Kryo registration section is corrupted; restoring a snapshot produced by an incompatible Flink version with a changed registration format; truncated checkpoint files (interrupted upload, HDFS corruption) so the tag byte reads garbage.

Common situations: Savepoint restore after partial/corrupted upload to object storage; mixing Flink versions between the job that wrote and the job that restores; bit rot or wrong file being passed with -s to 'flink run -s'.

Related errors

• Corrupted data to deserialize
• Error during Java serialization.
• Error during Java deserialization.
• The Kryo Output still contains data from a previous serializ
• Could not clone serializer instance of class {className}

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/67c9d61feba3732f. Report an issue: GitHub.