apache/pulsar · error · IllegalArgumentException

Invalid hash range format: hex

Error message

Invalid hash range format: hex

What it means

HashRange.fromHexString parses a range encoded as 'start-end' hex (as produced by toHexString, e.g. '00ff-01aa'). If the input has no '-' separator so split yields other than 2 parts, the string is not a valid serialized HashRange and IllegalArgumentException is thrown.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/scalable/HashRange.java:115

    }

    @Override
    public int compareTo(HashRange o) {
        int result = Integer.compare(start, o.start);
        if (result == 0) {
            result = Integer.compare(end, o.end);
        }
        return result;
    }

    public String toHexString() {
        return String.format("%04x-%04x", start, end);
    }

    public static HashRange fromHexString(String hex) {
        String[] parts = hex.split("-", 2);
        if (parts.length != 2) {
            throw new IllegalArgumentException("Invalid hash range format: " + hex);
        }
        return new HashRange(Integer.parseInt(parts[0], 16), Integer.parseInt(parts[1], 16));
    }

    @Override
    public String toString() {
        return "[" + String.format("%04x", start) + ", " + String.format("%04x", end) + "]";
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Pass the exact string produced by HashRange.toHexString
2. Validate the format matches /^[0-9a-fA-F]+-[0-9a-fA-F]+$/ before parsing
3. Check where the string was stored or transferred for truncation/re-encoding
4. Handle null/empty input before calling fromHexString

Example fix

// before
HashRange.fromHexString("00ff01aa");
// after
HashRange.fromHexString("00ff-01aa");

HashRange safeParse(String hex) {
    if (hex == null || !hex.matches("^[0-9a-fA-F]+-[0-9a-fA-F]+$")) {
        throw new IllegalArgumentException("Not a HashRange hex string: " + hex);
    }
    return HashRange.fromHexString(hex);
}

try {
    HashRange r = HashRange.fromHexString(s);
} catch (IllegalArgumentException e) {
    log.warn("Corrupt hash range '{}' - falling back to default", s);
}

When it happens

Trigger: Calling HashRange.fromHexString with a string lacking the '-' delimiter, e.g. '00ff01aa', an empty string, or a corrupted/truncated value from storage or the wire.

Common situations: Persisted range metadata manually edited or truncated; decoding a value produced by a different serializer or older version; off-by-one substring that dropped the hyphen.

Related errors

• Malformed configuration file
• No more range can assigned to new consumer, assigned consume
• Range conflict with consumer ${conflictingConsumer}
• Segments are not adjacent: ${hashRange1} and ${hashRange2}
• Invalid txnId key:

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/83fa95b8c62290e5. Report an issue: GitHub.