apache/cassandra · error · NumberFormatException

Non-hex characters in

Error message

Non-hex characters in 

What it means

Hex.hexToBytes looks up each character in its charToByte table; invalid characters map to -1. If either nibble of a byte is not a hex character (0-9, a-f, A-F), it throws NumberFormatException naming the offending string.

Source

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

        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);
    }

    public static String bytesToHex(byte bytes[], int offset, int length)
    {
        char[] c = new char[length * 2];
        for (int i = 0; i < length; i++)
        {
            int bint = bytes[i + offset];
            c[i * 2] = byteToChar[(bint & 0xf0) >> 4];
            c[1 + i * 2] = byteToChar[bint & 0x0f];

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Validate the string matches ^[0-9a-fA-F]+$ before calling hexToBytes
2. Strip common decorations such as '0x' prefix, whitespace, and separators
3. Fix the upstream source that generated the corrupted hex string

Example fix

// before
byte[] bytes = Hex.hexToBytes(value.replace("0x", ""));
// after
String hex = value.replace("0x", "").trim();
if (!hex.matches("[0-9a-fA-F]+"))
    throw new IllegalArgumentException("not hex: " + hex);
byte[] bytes = Hex.hexToBytes(hex);

if (str == null || !str.matches("[0-9a-fA-F]+")) throw new IllegalArgumentException("invalid hex: " + str);

try { bytes = Hex.hexToBytes(str); } catch (NumberFormatException e) { /* handle non-hex input */ }

When it happens

Trigger: Calling Hex.hexToBytes(str) with a string of even length that contains any non-hex character, e.g. 'zz12', '12 34' (space), or '0x12'.

Common situations: Passing strings with 0x prefixes; whitespace or separator characters from formatted logs; copy-paste artifacts; non-ASCII characters from encoding mishaps.

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

• An hex string representing bytes must have an even length
• A CQL blob string must have an even length (since one byte i
• cannot parse '%s' as hex bytes
• Invalid value for system property: expected integer value bu
• Invalid value for system property: expected long value but g

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