apache/flink · critical · IOException

Unrecognized version for TypeSerializerSnapshot format: {}

Error message

Unrecognized version for TypeSerializerSnapshot format: {}

What it means

Thrown by TypeSerializerSnapshotSerializationProxy.read when the format version read from the stream is not 2 (the only version handled). This proxy wraps the overall serializer-snapshot binary envelope (format version + snapshot class name + snapshot version + snapshot data). A version other than 2 means the stream was written by an incompatible serialization format or is corrupt.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/typeutils/TypeSerializerSnapshotSerializationUtil.java:126

            // write the format version of this utils format
            super.write(out);

            TypeSerializerSnapshot.writeVersionedSnapshot(out, serializerSnapshot);
        }

        @SuppressWarnings("unchecked")
        @Override
        public void read(DataInputView in) throws IOException {
            // read version
            super.read(in);
            final int version = getReadVersion();

            switch (version) {
                case 2:
                    serializerSnapshot = deserializeV2(in, userCodeClassLoader);
                    break;
                default:
                    throw new IOException(
                            "Unrecognized version for TypeSerializerSnapshot format: " + version);
            }
        }

        @Override
        public int getVersion() {
            return VERSION;
        }

        @Override
        public int[] getCompatibleVersions() {
            return new int[] {VERSION};
        }

        @Override
        public Optional<String> getAdditionalDetailsForIncompatibleVersion(int readVersion) {
            if (readVersion == 1) {
                return Optional.of(

View on GitHub (pinned to 2f3c205e92)

Solutions

Restore the checkpoint/savepoint with the Flink version that wrote it, then re-save and migrate.
Verify the checkpoint file is intact and not corrupt.
Ensure no third-party tool or custom code is rewriting serializer snapshot bytes in an incompatible way.

Defensive patterns

Strategy: validation

Validate before calling

// Verify Flink version alignment before restore — the proxy only supports format version 2
// Run: mvn dependency:tree -Dincludes=org.apache.flink

Try / catch

try {
    backend.restore(checkpointPath);
} catch (IOException e) {
    if (e.getMessage().contains("Unrecognized version for TypeSerializerSnapshot format")) {
        log.error("Snapshot proxy version not supported. Restore with the writing Flink version.");
    }
    throw e;
}

Prevention

Restore checkpoints with the Flink version that wrote them; take a fresh savepoint before upgrading.
Ensure all Flink JARs share one version to avoid format mismatches.
Do not manually edit or rewrite serializer snapshot bytes.

When it happens

Trigger: Reading a serializer snapshot written by a Flink version whose TypeSerializerSnapshotSerializationProxy used a different VERSION (the proxy only supports version 2). Also triggered by corrupted bytes where the version field is garbage, or by a stream that is not actually a serializer snapshot at all (misaligned read).

Common situations: Cross-version checkpoint restore where the proxy format changed between major Flink releases. Corrupted checkpoint metadata. Reading a hand-crafted or truncated binary stream as if it were a serializer snapshot.

Related errors

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