{"record":{"id":"b119fe6ff40dd6c4","repo":"apache/cassandra","slug":"expected-version-0-for-unversioned-serializer","errorCode":null,"errorMessage":"Expected version 0 for unversioned serializer","messagePattern":"Expected version 0 for unversioned serializer","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/io/util/CompressedFrameDataInputPlus.java","lineNumber":105,"sourceCode":"        buffer.flip();\n    }\n\n    public static <T> T read(File file, IVersionedSerializer<T> serializer) throws IOException\n    {\n        try (CompressedFrameDataInputPlus in = new CompressedFrameDataInputPlus(DEFAULT_FRAME_SIZE, file.newReadChannel(), ZstdCompressor.getOrCreate(DEFAULT_COMPRESSION_LEVEL), Crc.crc32()))\n        {\n            int version = in.readUnsignedVInt32();\n            return serializer.deserialize(in, version);\n        }\n    }\n\n    public static <T> T readOne(File file, UnversionedSerializer<T> serializer) throws IOException\n    {\n        try (CompressedFrameDataInputPlus in = new CompressedFrameDataInputPlus(DEFAULT_FRAME_SIZE, file.newReadChannel(), ZstdCompressor.getOrCreate(DEFAULT_COMPRESSION_LEVEL), Crc.crc32()))\n        {\n            int version = in.readUnsignedVInt32();\n            if (version != 0)\n                throw new IOException(\"Expected version 0 for unversioned serializer\");\n            return serializer.deserialize(in);\n        }\n    }\n\n    public static <T> List<T> readList(File file, UnversionedSerializer<T> serializer) throws IOException\n    {\n        try (CompressedFrameDataInputPlus in = new CompressedFrameDataInputPlus(DEFAULT_FRAME_SIZE, file.newReadChannel(), ZstdCompressor.getOrCreate(DEFAULT_COMPRESSION_LEVEL), Crc.crc32()))\n        {\n            int version = in.readUnsignedVInt32();\n            if (version != 0)\n                throw new IOException(\"Expected version 0 for unversioned serializer\");\n            return CollectionSerializers.deserializeList(in, serializer);\n        }\n    }\n}\n","sourceCodeStart":87,"sourceCodeEnd":121,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/util/CompressedFrameDataInputPlus.java#L87-L121","documentation":"CompressedFrameDataInputPlus.readOne reads a version prefix as unsigned VInt and requires it to be 0 because the supplied UnversionedSerializer has no version handling. A non-zero version means the file was written by a newer (or different) writer than this reader supports.","triggerScenarios":"Calling readOne(file, serializer) on a file whose first frame encodes a non-zero version — typically a file produced by CompressedFrameDataOutputPlus.write with a versioned serializer or by a newer Cassandra version.","commonSituations":"Upgrading/downgrading Cassandra and reading metadata files from another version; accidentally using readOne (unversioned) on a file written via the versioned read/write API path.","solutions":["Use CompressedFrameDataInputPlus.read(file, IVersionedSerializer) with a versioned serializer that understands the file's version.","Regenerate the file with a compatible writer version, or migrate it to version 0.","Check which Cassandra version wrote the file and use a reader from a compatible version."],"exampleFix":"// before\nT val = CompressedFrameDataInputPlus.readOne(file, myUnversionedSerializer);\n// after\nT val = CompressedFrameDataInputPlus.read(file, myVersionedSerializer); // handles version prefix\n","handlingStrategy":"validation","validationCode":"// peek the version prefix before choosing the API; if versioned data expected, use read() not readOne()","typeGuard":null,"tryCatchPattern":"try { return CompressedFrameDataInputPlus.readOne(file, ser); }\ncatch (IOException e) {\n    if (e.getMessage().contains(\"Expected version 0\")) return CompressedFrameDataInputPlus.read(file, versionedSer);\n    throw e;\n}","preventionTips":["Match readOne/readList to files written by unversioned serializers only","Track the Cassandra version that wrote each file","Prefer the versioned read/write API when format may evolve"],"tags":["io","versioning","serializer","compatibility"],"backgroundTag":"incompatible-source-type","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}