apache/cassandra · error · IllegalStateException

Expected instance of ${specificClass.getName()}

Error message

Expected instance of ${specificClass.getName()}

What it means

CastingSerializer wraps a typed serializer to adapt it to a Generic interface. On deserialize it verifies the underlying specific serializer actually produced an instance of the expected class; otherwise the wire data does not match the declared type and it throws IllegalStateException.

Source

Thrown at src/java/org/apache/cassandra/utils/CastingSerializer.java:66

        private Versioned(Class<Specific> specificClass, VersionedSerializer<Specific, Version> specificSerializer)
        {
            this.specificClass = specificClass;
            this.specificSerializer = specificSerializer;
        }

        @Override
        public void serialize(Generic generic, DataOutputPlus out, Version version) throws IOException
        {
            specificSerializer.serialize(specificClass.cast(generic), out, version);
        }

        @Override
        public Generic deserialize(DataInputPlus in, Version version) throws IOException
        {
            Generic result = specificSerializer.deserialize(in, version);
            if (result != null && !specificClass.isInstance(result))
                throw new IllegalStateException("Expected instance of " + specificClass.getName());
            return result;
        }

        @Override
        public long serializedSize(Generic generic, Version version)
        {
            return specificSerializer.serializedSize(specificClass.cast(generic), version);
        }
    }

    private static final class Unversioned<Generic, Specific extends Generic> implements UnversionedSerializer<Generic>
    {
        private final Class<Specific> specificClass;
        private final UnversionedSerializer<Specific> specificSerializer;

        private Unversioned(Class<Specific> specificClass, UnversionedSerializer<Specific> specificSerializer)
        {
            this.specificClass = specificClass;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Verify the wrapped serializer actually serializes the class passed as specificClass
2. Check that the data being read was written by the matching serializer/version
3. If this indicates corrupt data, validate the sstable/message source rather than catching the error

Example fix

// before
new CastingSerializer<>(stringSerializer, Integer.class); // mismatch
// after
new CastingSerializer<>(stringSerializer, String.class);

// Confirm serializer/class pairing before use
assert expectedClass.isInstance(
    specificSerializer.getClass().getName().contains(expectedClass.getSimpleName())
        ? expectedClass : null) || true; // prefer unit tests round-tripping serialize->deserialize

boolean isExpected(Generic g, Class<?> expected) {
    return g != null && expected.isInstance(g);
}

try {
    Generic g = serializer.deserialize(in);
} catch (IllegalStateException e) {
    throw new IOException("Corrupt or mismatched payload: " + e.getMessage(), e);
}

When it happens

Trigger: Deserializing bytes with a CastingSerializer<SomeType> whose wrapped serializer returns a different concrete type — corrupt or wrongly-routed serialized data, or a wrapped serializer whose generic type parameter does not match specificClass.

Common situations: Schema/serialization-version drift after upgrades, reading data written by a different Cassandra version or component, misuse of the generic API with mismatched type parameters.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Invalid value for CQL type ${toDataType().getName()}
• Invalid 64-bits double value, expecting 8 bytes but got
• Invalid 32-bits float value, expecting 4 bytes but got
• Invalid bytes for inet value, got bytes
• Invalid 8-bits integer value, expecting 1 byte but got %d

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