apache/cassandra · error

error

Error message

error: {message}

What it means

NodeTool's picocli command execution wraps arbitrary command exceptions: if the root cause is a parse/usage problem (ParameterException) or an IllegalStateException it reports bad use and exits 1; otherwise it prints the root cause via err() and exits 2. The user-visible 'error: {message}' comes from badUse/exception handling during nodetool command execution.

Solutions

1. Check nodetool help <command> for correct syntax and rerun with valid arguments
2. Verify the node is up and JMX (port 7199) is reachable before running the command
3. Inspect the printed root-cause message and server logs (system.log) for the underlying exception
4. If IllegalStateException, ensure the node is in a valid state (e.g. NORMAL) for the requested operation

Example fix

// before
$ nodetool scrub  // missing keyspace/table args -> error, exit 1
// after
$ nodetool help scrub
$ nodetool scrub keyspace1 standard1

// validate arguments before invoking nodetool
if (keyspace == null || tables == null || tables.length == 0)
    throw new IllegalArgumentException("Usage: nodetool <command> <keyspace> <table>...");
boolean nodeUp = java.net.SocketTimeoutException.class.cast(null) == null
    && tryProbeJmx(host, port); // e.g. open JMX connection and call isRunning first

try {
    int rc = nodeTool.execute(command, args);
} catch ( picocli.ParameterException | IllegalStateException e) {
    // bad use: fix syntax or node state, exit 1
} catch (Exception e) {
    Throwable root = org.apache.cassandra.utils.Throwables.getRootCause(e);
    // inspect root.getMessage(); check system.log; exit 2
}

When it happens

Trigger: Running any nodetool command whose execution throws — e.g. invalid arguments/options (picocli ParameterException), command invoked while the node is down or in a state making the operation illegal (IllegalStateException), or an underlying JMX/runtime exception surfaced as the root cause.

Common situations: Typo'd or missing command arguments; running nodetool against a node that hasn't finished startup; calling a command (e.g. decommission, rebuild) while the node is in a state that forbids it; node down / JMX connection failures.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• argument for sort must be one of
• argument for top must be a positive integer.
• Argument must have keyspace and table values.
• arguments for -F are json,yaml only.
• arguments for -F are json,yaml only.

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/NodeTool.java:117

    {
        try
        {
            CommandLine commandLine = createCommandLine(new CassandraCliFactory(nodeProbeFactory, output));
            commandLine.setOut(new PrintWriter(output.out, true));
            commandLine.setErr(new PrintWriter(output.err, true));

            configureCliLayout(commandLine);
            commandLine.setExecutionStrategy(JmxConnect::executionStrategy)
                       .setExecutionExceptionHandler((ex, c, arg) -> {
                           // Used for backward compatibility, some commands are validated when a command is run.
                           if (ex instanceof IllegalArgumentException |
                               ex instanceof IllegalStateException)
                           {
                               badUse(ex);
                               return 1;
                           }

                           err(Throwables.getRootCause(ex));
                           return 2;
                       })
                       .setParameterExceptionHandler((ex, arg) -> {
                           badUse(ex);
                           return 1;
                       })
                       // Some of the Cassandra commands don't comply with the POSIX standard, so we need to disable such options.
                       // Example: ./nodetool -h localhost -p 7100 repair mykeyspayce -hosts 127.0.0.1,127.0.0.2
                       //
                       // This also means that option parameters must be separated from the option name by whitespace
                       // or the = separator character, so -D key=value and -D=key=value will be recognized but
                       // -Dkey=value will not.
                       .setPosixClusteredShortOptionsAllowed(false);

            printHistory(args);
            return commandLine.execute(relocatePrintPortOptionsForBackwardCompatibility(args));
        }
        catch (ConfigurationException e)

View on GitHub (pinned to 88fd0f6a0e)