{"record":{"id":"48e95cb7f070cb45","repo":"apache/flink","slug":"unrecognized-version-for-typeserializersnapshot-fo","errorCode":null,"errorMessage":"Unrecognized version for TypeSerializerSnapshot format: {}","messagePattern":"Unrecognized version for TypeSerializerSnapshot format: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"flink-core/src/main/java/org/apache/flink/api/common/typeutils/TypeSerializerSnapshotSerializationUtil.java","lineNumber":126,"sourceCode":"            // write the format version of this utils format\n            super.write(out);\n\n            TypeSerializerSnapshot.writeVersionedSnapshot(out, serializerSnapshot);\n        }\n\n        @SuppressWarnings(\"unchecked\")\n        @Override\n        public void read(DataInputView in) throws IOException {\n            // read version\n            super.read(in);\n            final int version = getReadVersion();\n\n            switch (version) {\n                case 2:\n                    serializerSnapshot = deserializeV2(in, userCodeClassLoader);\n                    break;\n                default:\n                    throw new IOException(\n                            \"Unrecognized version for TypeSerializerSnapshot format: \" + version);\n            }\n        }\n\n        @Override\n        public int getVersion() {\n            return VERSION;\n        }\n\n        @Override\n        public int[] getCompatibleVersions() {\n            return new int[] {VERSION};\n        }\n\n        @Override\n        public Optional<String> getAdditionalDetailsForIncompatibleVersion(int readVersion) {\n            if (readVersion == 1) {\n                return Optional.of(","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/common/typeutils/TypeSerializerSnapshotSerializationUtil.java#L108-L144","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Verify Flink version alignment before restore — the proxy only supports format version 2\n// Run: mvn dependency:tree -Dincludes=org.apache.flink","typeGuard":null,"tryCatchPattern":"try {\n    backend.restore(checkpointPath);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"Unrecognized version for TypeSerializerSnapshot format\")) {\n        log.error(\"Snapshot proxy version not supported. Restore with the writing Flink version.\");\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["serialization","checkpoint","savepoint","version-mismatch","state","io"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}