apache/cassandra · error · IllegalArgumentException

Invalid TokenRange:

Error message

Invalid TokenRange: 

What it means

TokenRange.parse() validates that a serialized token range string contains exactly two comma-separated bounds after the optional TableId:: prefix. If the split produces a different number of parts, the string is malformed and IllegalArgumentException('Invalid TokenRange: <str>') is thrown. This is a strict format check on human/tool-provided range strings like 'tableId::[start, end]'.

Source

Thrown at src/java/org/apache/cassandra/service/accord/TokenRange.java:208

        public long serializedSize(TokenRange t)
        {
            return TokenKey.noTableSerializer.serializedSize(t.start())
                   + TokenKey.noTableSerializer.serializedSize(t.end());
        }
    };

    public static TokenRange parse(String str, IPartitioner partitioner)
    {
        TableId tableId;
        {
            int split = str.indexOf(':', str.startsWith("tid:") ? 4 : 0);
            tableId = TableId.fromString(str.substring(0, split));
            str = str.substring(split + 2, str.length() - 1);
        }

        String[] bounds = str.split(",");
        if (bounds.length != 2)
            throw new IllegalArgumentException("Invalid TokenRange: " + str);

        return new TokenRange(TokenKey.parse(tableId, bounds[0], partitioner), TokenKey.parse(tableId, bounds[1], partitioner));
    }

}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Provide a well-formed string of the form '<tableId>::[<start>, <end>]' (or '[<start>, <end>]' without tableId) with exactly two bounds
2. Print/log the failing string from the exception message and fix the offending producer (script, tool, or serializer)
3. Trim whitespace and strip stray brackets before parsing
4. Regenerate the range list from ClusterMetadata/TokenRange.toString() rather than hand-crafting strings

Example fix

// before
TokenRange range = TokenRange.parse(partitioner, "tbl::[9223372036854775807,)");
// IllegalArgumentException: Invalid TokenRange: [9223372036854775807,)
// after
TokenRange range = TokenRange.parse(partitioner, "tbl::[9223372036854775807, -9223372036854775808]");

String[] bounds = str.substring(str.indexOf("[") + 1, str.length() - 1).split(",");
if (bounds.length != 2) throw new IllegalArgumentException("expected [start, end]: " + str);
TokenRange r = TokenRange.parse(partitioner, str);

try { return TokenRange.parse(partitioner, str); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Malformed token range '" + str + "': expected '<tableId>::[<start>, <end>]'", e); }

When it happens

Trigger: Passing a malformed string to TokenRange.parse (e.g. missing a bound like 'tbl::[10,)' or '(10]', extra commas, wrong bracket placement, missing both bounds), typically from node-tool output parsing, JMX, or hand-written scripts.

Common situations: Parsing ranges copy-pasted from logs with truncated output; building range strings programmatically with null/empty bounds; format changes between Cassandra versions altering the serialized form; typos in hand-written range arguments.

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.

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Unable to convert '%s' to a duration
• Unknown duration symbol '%s'
• Timestamp format must be hh:mm:ss[.fffffffff]
• Hour out of bounds.
• Minute out of bounds.

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