apache/cassandra · error · IOException

Expected version 0 for unversioned serializer

Error message

Expected version 0 for unversioned serializer

What it means

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.

Solutions

  1. Use CompressedFrameDataInputPlus.read(file, IVersionedSerializer) with a versioned serializer that understands the file's version.
  2. Regenerate the file with a compatible writer version, or migrate it to version 0.
  3. Check which Cassandra version wrote the file and use a reader from a compatible version.

Example fix

// before
T val = CompressedFrameDataInputPlus.readOne(file, myUnversionedSerializer);
// after
T val = CompressedFrameDataInputPlus.read(file, myVersionedSerializer); // handles version prefix
Defensive patterns

Strategy: validation

Validate before calling

// peek the version prefix before choosing the API; if versioned data expected, use read() not readOne()

Try / catch

try { return CompressedFrameDataInputPlus.readOne(file, ser); }
catch (IOException e) {
    if (e.getMessage().contains("Expected version 0")) return CompressedFrameDataInputPlus.read(file, versionedSer);
    throw e;
}

Prevention

When it happens

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

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

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/b119fe6ff40dd6c4. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/io/util/CompressedFrameDataInputPlus.java:105

        buffer.flip();
    }

    public static <T> T read(File file, IVersionedSerializer<T> serializer) throws IOException
    {
        try (CompressedFrameDataInputPlus in = new CompressedFrameDataInputPlus(DEFAULT_FRAME_SIZE, file.newReadChannel(), ZstdCompressor.getOrCreate(DEFAULT_COMPRESSION_LEVEL), Crc.crc32()))
        {
            int version = in.readUnsignedVInt32();
            return serializer.deserialize(in, version);
        }
    }

    public static <T> T readOne(File file, UnversionedSerializer<T> serializer) throws IOException
    {
        try (CompressedFrameDataInputPlus in = new CompressedFrameDataInputPlus(DEFAULT_FRAME_SIZE, file.newReadChannel(), ZstdCompressor.getOrCreate(DEFAULT_COMPRESSION_LEVEL), Crc.crc32()))
        {
            int version = in.readUnsignedVInt32();
            if (version != 0)
                throw new IOException("Expected version 0 for unversioned serializer");
            return serializer.deserialize(in);
        }
    }

    public static <T> List<T> readList(File file, UnversionedSerializer<T> serializer) throws IOException
    {
        try (CompressedFrameDataInputPlus in = new CompressedFrameDataInputPlus(DEFAULT_FRAME_SIZE, file.newReadChannel(), ZstdCompressor.getOrCreate(DEFAULT_COMPRESSION_LEVEL), Crc.crc32()))
        {
            int version = in.readUnsignedVInt32();
            if (version != 0)
                throw new IOException("Expected version 0 for unversioned serializer");
            return CollectionSerializers.deserializeList(in, serializer);
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)