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

Invalid IP address ( . . . ) while deserializing inet…

Error message

Invalid IP address (%d.%d.%d.%d) while deserializing inet address

What it means

Thrown when the native protocol driver sends an inet address whose byte array cannot be converted to an InetAddress. CBUtil deserializes the address bytes from the frame; if the byte length is not a valid address size (4 or 16 bytes), InetAddress.getByAddress throws UnknownHostException and this ProtocolException is raised, which closes the connection.

Solutions

Fix the client to serialize the inet address as exactly 4 bytes (IPv4) or 16 bytes (IPv6) followed by the 4-byte port.
Check the driver version matches the server's supported protocol versions (negotiate via STARTUP).
Inspect traffic with a proxy (e.g. tcpdump or a CQL proxy) to verify the frame's inet field length byte.
Capture the offending frame and reproduce with a minimal client to confirm serialization is correct.

Example fix

// before: address serialized with wrong length
byte[] address = hostname.getBytes();
// after: serialize raw IP bytes + port
byte[] address = InetAddress.getByName("10.0.0.1").getAddress(); // 4 or 16 bytes
buffer.writeInt(address.length);
buffer.writeBytes(address);
buffer.writeInt(port);

Defensive patterns

Strategy: validation

Validate before calling

byte[] address = inet.getAddress().getAddress();
if (address.length != 4 && address.length != 16)
    throw new IllegalArgumentException("inet address must be 4 or 16 bytes, got " + address.length);

Type guard

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

Try / catch

try { ... } catch (com.datastax.driver.core.exceptions.NoNodeAvailableException | ProtocolException e) {
    log.error("Malformed inet in frame, closing connection", e);
}

Prevention

Use an official Cassandra driver instead of hand-rolled protocol serialization.
Always derive address bytes from InetAddress.getAddress(), never from string/hostname bytes.
Add integration tests that serialize/deserialize both IPv4 and IPv6 inet values.
Log the frame hex dump before connecting to spot length errors early.

When it happens

Trigger: A client sends an OPTIONS/STARTUP or other frame containing an inet value whose address byte array length is neither 4 nor 16 bytes (malformed serialization, buggy driver, corrupted frame).

Common situations: Custom or hand-rolled CQL binary protocol clients; middleware/proxies rewriting frames; fuzzer-generated or corrupted traffic; drivers built for a different protocol version.

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

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

Appendix: source

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

            s.add(readString(cb));
            l[i] = readBoundValueAsByteArray(cb, protocolVersion);
        }
        return Pair.create(s, l);
    }

    public static InetSocketAddress readInet(ByteBuf cb)
    {
        int addrSize = cb.readByte() & 0xFF;
        byte[] address = new byte[addrSize];
        cb.readBytes(address);
        int port = cb.readInt();
        try
        {
            return new InetSocketAddress(InetAddress.getByAddress(address), port);
        }
        catch (UnknownHostException e)
        {
            throw new ProtocolException(String.format("Invalid IP address (%d.%d.%d.%d) while deserializing inet address", address[0], address[1], address[2], address[3]));
        }
    }

    public static void writeInet(InetSocketAddress inet, ByteBuf cb)
    {
        byte[] address = inet.getAddress().getAddress();

        cb.writeByte(address.length);
        cb.writeBytes(address);
        cb.writeInt(inet.getPort());
    }

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

View on GitHub (pinned to 88fd0f6a0e)