apache/cassandra · error · IllegalArgumentException

Server is not initialized yet, cannot run nodetool.

Error message

Server is not initialized yet, cannot run nodetool.

What it means

NodeTool's err() is the generic failure reporter for nodetool commands. When the underlying failure is a JMX InstanceNotFoundException, it converts it into an IllegalArgumentException stating the server is not initialized, because the MBean (Cassandra's storage service) has not yet been registered in the platform MBean server, so nodetool cannot operate.

Source

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

                break;
            case PICOCLI:
                break;
            default:
                throw new IllegalStateException("Unknown CLI layout: " + layout);
        }
    }

    protected void badUse(Exception e)
    {
        output.out.println("nodetool: " + e.getMessage());
        output.out.println("See 'nodetool help' or 'nodetool help <command>'.");
    }

    protected void err(Throwable e)
    {
        // CASSANDRA-11537: friendly error message when server is not ready
        if (e instanceof InstanceNotFoundException)
            throw new IllegalArgumentException("Server is not initialized yet, cannot run nodetool.");

        output.err.println("error: " + e.getMessage());
        output.err.println("-- StackTrace --");
        output.err.println(getStackTraceAsString(e));
    }

    /**
     * Rewrites global {@code -pp/--print-port} options that have been moved
     * to subcommands via @Mixin for backward compatibility. When a user types:
     * <pre>
     *   nodetool -pp status
     *   nodetool --print-port status -r
     * </pre>
     * this method rewrites them to:
     * <pre>
     *   nodetool status -pp
     *   nodetool status -r --print-port
     * </pre>

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Wait until Cassandra has fully started (check system.log for 'Startup complete' or poll `nodetool status` in a retry loop) before running nodetool
2. Verify you are connecting to the correct JMX host/port (default 7199) of an actual Cassandra node
3. Check Cassandra logs for startup failure/hang and fix the underlying startup problem
4. Add retries/backoff in automation so nodetool runs only once the node is up

Example fix

// before (script)
nodetool status
// after (retry until node is up)
until nodetool status >/dev/null 2>&1; do echo "waiting for node..."; sleep 5; done
nodetool status

#!/bin/bash
until nodetool status >/dev/null 2>&1; do sleep 5; done
nodetool "$@"

When it happens

Trigger: Running any nodetool command against a node whose server side (MBeans) is not yet registered — i.e. Cassandra is still starting up, is shutting down, or the JMX connection resolved but the expected MBean is absent. err() is called from NodeTool's execute path after the command threw InstanceNotFoundException.

Common situations: Scripts that run nodetool immediately after restarting Cassandra before it finishes startup; node crashed mid-boot so JMX agent is up but MBeans are not registered; connecting to the wrong host/port where a different JMX app is running; Cassandra hanging during startup (e.g. bootstrap or schema disagreement) so MBeans never appear.

Related errors

• Node is not yet bootstrapped completely. Use nodetool to che
• No configured daemon
• %s is not a valid JMX resource name
• JAAS login configuration missing for JMX authenticator setup
• Authentication error

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