apache/cassandra · error · java.lang.IllegalArgumentException

Invalid specification:

Error message

Invalid specification: 

What it means

AlterTopology.parseArgs parses a comma-separated list of nodeId=dc/rack specifications for topology changes. If a segment does not split into exactly two '=' separated non-empty parts, IllegalArgumentException 'Invalid specification' is thrown. This is strict input validation before any cluster change is committed.

Solutions

1. Correct the argument to 'nodeId=dc:rack' pairs separated by commas, e.g. 'id1=dc1:r1,id2=dc2:r2'
2. Quote the whole argument in the shell so '=' and ',' are not mangled
3. Check each segment contains exactly one '=' with non-empty id and location

Example fix

// before
nodetool altertopology 'id1=dc1,id2'   // 'id2' has no =value
// after
nodetool altertopology 'id1=dc1:r1,id2=dc2:r2'

// validate each change segment before invoking
for (String seg : changes.split(",")) {
    String[] parts = seg.trim().split("=");
    if (parts.length != 2 || parts[0].isEmpty() || parts[1].isEmpty())
        throw new IllegalArgumentException("bad segment: " + seg);
}

try { parseArgs(args, directory); }
catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid specification:")) { /* show usage and the offending segment */ }
    else throw e;
}

When it happens

Trigger: Calling AlterTopology.parseArgs (or the exposing tool/API) with a malformed change string such as 'a=b=c', 'nodewithnovalue', or empty '=' halves, e.g. 'id1=dc1,id2' or '=dc1'.

Common situations: Typo in nodetool/classictool topology arguments; shell quoting stripping the '=' side; copying examples with wrong format; whitespace/newline contamination in batch scripts.

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

• Invalid node identifier supplied:
• Multiple updates for node
• Illegal distribution specification:
• Illegal distribution type:
• Invalid parameter

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tcm/transformations/AlterTopology.java:70

    public static final Serializer serializer = new Serializer();

    private final Map<NodeId, Location> updates;
    private final PlacementProvider placementProvider;

    public AlterTopology(Map<NodeId, Location> updates, PlacementProvider placementProvider)
    {
        this.updates = updates;
        this.placementProvider = placementProvider;
    }

    public static Map<NodeId, Location> parseArgs(String args, Directory directory)
    {
        Map<NodeId, Location> asMap = new HashMap<>();
        for (String change : args.split(","))
        {
            String[] parts = change.trim().split("=");
            if (parts.length != 2)
                throw new IllegalArgumentException("Invalid specification: " + change);

            if (parts[0].isEmpty() || parts[1].isEmpty())
                throw new IllegalArgumentException("Invalid specification: " + change);

            NodeId id = getNodeIdFromString(parts[0].trim(), directory);
            if (asMap.containsKey(id))
                throw new IllegalArgumentException("Multiple updates for node " + id + " (" + parts[0].trim() + " )");
            asMap.put(getNodeIdFromString(parts[0].trim(), directory), Location.fromString(parts[1].trim()));
        }
        return asMap;
    }

    private static NodeId getNodeIdFromString(String s, Directory directory)
    {
        // first try to parse the id as a node id, either in UUID or int form
        try
        {
            return NodeId.fromString(s);

View on GitHub (pinned to 88fd0f6a0e)