apache/cassandra · error · MarshalException

Expected 4 or 16 byte inetaddress; got

Error message

Expected 4 or 16 byte inetaddress; got %s

What it means

InetAddressSerializer.validate() attempts InetAddress.getByAddress() on the raw bytes and converts any UnknownHostException into a MarshalException. Java only accepts 4-byte (IPv4) or 16-byte (IPv6) arrays as raw addresses, so any other length fails. This guarantees an inet column only holds well-formed IP addresses.

Solutions

1. Resolve hostnames to an IP first (InetAddress.getByName) and serialize the resulting address bytes (4 or 16 bytes) rather than the hostname text.
2. Verify the byte length before writing: exactly 4 for IPv4 or 16 for IPv6.
3. Do not include port or scope bytes; serialize only InetAddress.getAddress().
4. If textual data is intended, change the column type to text instead of inet.

Example fix

// before
ByteBuffer bytes = ByteBuffer.wrap("example.com".getBytes());
// after
InetAddress addr = InetAddress.getByName("example.com");
ByteBuffer bytes = ByteBuffer.wrap(addr.getAddress());

byte[] a = addr.getAddress(); if (a.length != 4 && a.length != 16) throw new IllegalArgumentException("inet needs 4 or 16 bytes");

boolean isValidInetBytes(java.net.InetAddress a) { byte[] b = a.getAddress(); return b.length == 4 || b.length == 16; }

try { inetType.validate(buf, accessor); } catch (org.apache.cassandra.exceptions.MarshalException e) { throw new IllegalArgumentException("bad inet value: " + e.getMessage(), e); }

When it happens

Trigger: Calling InetAddressSerializer.validate(value, accessor) (directly or via an InetType column) with bytes that are not 4 or 16 bytes long, or otherwise rejected by InetAddress.getByAddress (e.g. truncated buffer, a hostname string's bytes instead of address bytes).

Common situations: Writing a hostname string (e.g. "example.com") as bytes into an inet column instead of a resolved IP; writing an IPv6 address with a wrong/abbreviated byte length; ETL tools exporting addresses as text without resolution; client library serializing InetSocketAddress including port bytes.

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

• EmptyType only accept empty values
• Expected 4 or 0 byte int
• Expected 4 or 0 byte value for a float
• Expected 0 or at least 4 bytes
• Expected 2 bytes for a smallint

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

Appendix: source

Thrown at src/java/org/apache/cassandra/serializers/InetAddressSerializer.java:63

    }

    public ByteBuffer serialize(InetAddress value)
    {
        return value == null ? ByteBufferUtil.EMPTY_BYTE_BUFFER : ByteBuffer.wrap(value.getAddress());
    }

    public <V> void validate(V value, ValueAccessor<V> accessor) throws MarshalException
    {
        if (accessor.isEmpty(value))
            return;

        try
        {
            InetAddress.getByAddress(accessor.toArray(value));
        }
        catch (UnknownHostException e)
        {
            throw new MarshalException(String.format("Expected 4 or 16 byte inetaddress; got %s", accessor.toHex(value)));
        }
    }

    public String toString(InetAddress value)
    {
        return value == null ? "" : value.getHostAddress();
    }

    public Class<InetAddress> getType()
    {
        return InetAddress.class;
    }

    @Override
    public boolean shouldQuoteCQLLiterals()
    {
        return true;
    }

View on GitHub (pinned to 88fd0f6a0e)