apache/cassandra · error · NumberFormatException

An hex string representing bytes must have an even length

Error message

An hex string representing bytes must have an even length

What it means

Hex.hexToBytes converts a hexadecimal string to a byte array. It throws NumberFormatException before parsing when the input string has an odd number of characters, because each byte requires exactly two hex digits and an odd-length string cannot represent whole bytes.

Source

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

                charToByte[c] = (byte)(c - '0');
            else if (c >= 'A' && c <= 'F')
                charToByte[c] = (byte)(c - 'A' + 10);
            else if (c >= 'a' && c <= 'f')
                charToByte[c] = (byte)(c - 'a' + 10);
            else
                charToByte[c] = (byte)-1;
        }

        for (int i = 0; i < 16; ++i)
        {
            byteToChar[i] = Integer.toHexString(i).charAt(0);
        }
    }

    public static byte[] hexToBytes(String str)
    {
        if (str.length() % 2 == 1)
            throw new NumberFormatException("An hex string representing bytes must have an even length");

        byte[] bytes = new byte[str.length() / 2];
        for (int i = 0; i < bytes.length; i++)
        {
            byte halfByte1 = charToByte[str.charAt(i * 2)];
            byte halfByte2 = charToByte[str.charAt(i * 2 + 1)];
            if (halfByte1 == -1 || halfByte2 == -1)
                throw new NumberFormatException("Non-hex characters in " + str);
            bytes[i] = (byte)((halfByte1 << 4) | halfByte2);
        }
        return bytes;
    }

    public static String bytesToHex(byte... bytes)
    {
        return bytesToHex(bytes, 0, bytes.length);
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Check str.length() % 2 == 0 before calling hexToBytes and pad or reject the input
Pad odd-length input with a leading '0' if it represents a single nibble
Trace where the hex string is produced and fix the producer to always emit even-length output

Example fix

// before
byte[] bytes = Hex.hexToBytes(userHex);
// after
if (userHex.length() % 2 != 0)
    userHex = "0" + userHex; // or reject
byte[] bytes = Hex.hexToBytes(userHex);

Defensive patterns

Strategy: validation

Validate before calling

if (str == null || str.length() % 2 != 0) throw new IllegalArgumentException("hex string must have even length: " + str);

Try / catch

try { bytes = Hex.hexToBytes(str); } catch (NumberFormatException e) { /* reject or pad input */ }

Prevention

Validate hex input length and character set at system boundaries
Always produce hex via Hex.bytesToHex rather than hand-rolling
Add unit tests for odd-length and padded inputs

When it happens

Trigger: Calling Hex.hexToBytes(str) with a string whose length % 2 == 1, e.g. 'abc' or '7f1'.

Common situations: Hand-written hex constants missing a digit; truncation when copying tokens/digests; concatenating hex fragments where a leading zero was dropped (e.g. 'f0a' instead of '0f0a').

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/dcffaba53ea095a3. Report an issue: GitHub.