apache/dubbo · error · IllegalArgumentException

invalid hex byte '%s' at index %d of '%s'

Error message

invalid hex byte '%s' at index %d of '%s'

What it means

Thrown by StringUtils.decodeHexByte(CharSequence s, int pos) when the two characters at pos and pos+1 are not valid hexadecimal digits. Each character is decoded via a lookup table (HEX2B); if either returns -1, the byte is invalid and an IllegalArgumentException is thrown with the offending substring, position, and full input.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/utils/StringUtils.java:1235

        sb.append(']');
        return sb.toString();
    }

    public static int decodeHexNibble(final char c) {
        // Character.digit() is not used here, as it addresses a larger
        // set of characters (both ASCII and full-width latin letters).
        byte[] hex2b = HEX2B;
        return c < hex2b.length ? hex2b[c] : -1;
    }

    /**
     * Decode a 2-digit hex byte from within a string.
     */
    public static byte decodeHexByte(CharSequence s, int pos) {
        int hi = decodeHexNibble(s.charAt(pos));
        int lo = decodeHexNibble(s.charAt(pos + 1));
        if (hi == -1 || lo == -1) {
            throw new IllegalArgumentException(
                    String.format("invalid hex byte '%s' at index %d of '%s'", s.subSequence(pos, pos + 2), pos, s));
        }
        return (byte) ((hi << 4) + lo);
    }

    /**
     * Creates a comma-delimited string from one or more string values.
     *
     * @param one    the first string value
     * @param others additional string values
     * @return the combined string, or null if the first value is null
     * @since 2.7.8
     */
    public static String toCommaDelimitedString(String one, String... others) {
        if (one == null) {
            return null;
        }
        if (others == null) {

View on GitHub (pinned to 3a3043227f)

Solutions

1. Validate the input is purely hex before calling: s.toString().matches("^[0-9a-fA-F]+$").
2. Strip separators (dashes, colons, spaces) from the input before decoding.
3. Verify pos and pos+1 are within bounds and point at hex characters.

Example fix

// before
byte b = StringUtils.decodeHexByte("ab-cd", 0);
// the '-' at index 2 is not valid, but also pos alignment may be wrong

// after
String clean = "ab-cd".replace("-", "");
byte b = StringUtils.decodeHexByte(clean, 0);

String s2 = s.toString();
if (pos + 1 >= s2.length()) throw new IllegalArgumentException("pos out of range");
char c1 = s2.charAt(pos), c2 = s2.charAt(pos + 1);
if (!"0123456789abcdefABCDEF".contains(String.valueOf(c1)) ||
    !"0123456789abcdefABCDEF".contains(String.valueOf(c2))) {
    throw new IllegalArgumentException("non-hex character at pos " + pos);
}

When it happens

Trigger: Passing a string where the characters at the specified position are not 0-9, a-f, A-F (or full-width equivalents); pos pointing at whitespace or a separator inside a hex string; off-by-one in pos that lands on a non-hex delimiter.

Common situations: Decoding a hex-encoded ID or hash with embedded dashes (e.g. UUID format) without stripping separators; malformed or truncated input from a network source; encoding mismatch (base64 passed where hex expected).

Related errors

• unterminated escape sequence at index ${i} of: ${str}
• bytes2base64: length < 0, length is {}
• bytes2base64: offset + length > array length.
• hex string format error [${c}].
• type [ ${type} ] is unsupported

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/7bce363dfed62c82. Report an issue: GitHub.