apache/cassandra · error · org.apache.cassandra.transport.ProtocolException

Invalid IP address while deserializing inet address

Error message

Invalid IP address while deserializing inet address

What it means

Same family as the inet-socket deserialization error: CBUtil reads an address byte array from a protocol frame and calls InetAddress.getByAddress, which rejects arrays that are not 4 or 16 bytes long, resulting in this ProtocolException. The connection is closed with an ERROR frame.

Solutions

1. Ensure the address byte array is exactly 4 bytes for IPv4 or 16 bytes for IPv6 before sending.
2. Upgrade/fix the client driver; verify it uses the standard inet serialization (length-prefixed bytes + port where applicable).
3. Enable driver debug logging and server-side protocol tracing to identify the malformed frame.
4. Send the value through an official driver instead of hand-rolled serialization.

Example fix

// before
byte[] bad = new byte[]{1,2,3}; // 3 bytes -> UnknownHostException
// after
byte[] ok = InetAddress.getByName("192.168.1.5").getAddress(); // always 4 or 16 bytes

byte[] address = ...;
if (address == null || (address.length != 4 && address.length != 16))
    throw new IllegalArgumentException("Address bytes must be exactly 4 (IPv4) or 16 (IPv6) bytes long");

boolean isValidInetAddr(byte[] a) { return a != null && (a.length == 4 || a.length == 16); }

try { session.execute(...); } catch (ProtocolException e) {
    log.error("Invalid inet bytes sent; check serialization", e);
}

When it happens

Trigger: A frame contains an inet address field with an invalid byte-array length (not 4 or 16), typically from a malformed client-side serialization.

Common situations: Custom CQL drivers, protocol fuzzing, bytecode-corrupting proxies, or a driver bug writing UDT/collection values containing inet elements.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid IP address ( . . . ) while deserializing inet…
• e.getMessage()
• Event " + eventType.name() + " not valid for protocol…
• Invalid BATCH message type
• Invalid query kind in BATCH messages. Must be 0 or 1 but…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/transport/CBUtil.java:718

    public static int sizeOfInet(InetSocketAddress inet)
    {
        byte[] address = inet.getAddress().getAddress();
        return 1 + address.length + 4;
    }

    public static InetAddress readInetAddr(ByteBuf cb)
    {
        int addressSize = cb.readByte() & 0xFF;
        byte[] address = new byte[addressSize];
        cb.readBytes(address);
        try
        {
            return InetAddress.getByAddress(address);
        }
        catch (UnknownHostException e)
        {
            throw new ProtocolException("Invalid IP address while deserializing inet address");
        }
    }

    public static void writeInetAddr(InetAddress inetAddr, ByteBuf cb)
    {
        byte[] address = inetAddr.getAddress();
        cb.writeByte(address.length);
        cb.writeBytes(address);
    }

    public static int sizeOfInetAddr(InetAddress inetAddr)
    {
        return 1 + inetAddr.getAddress().length;
    }

    /*
     * Reads *all* readable bytes from {@code cb} and return them.
     */

View on GitHub (pinned to 88fd0f6a0e)