apache/cassandra · critical · RuntimeException

Failed to initialize command line hierarchy

Error message

Failed to initialize command line hierarchy

What it means

NodeTool builds its command hierarchy from picocli CommandSpec factories (CassandraCliFactory backed by a live NodeProbeFactory). If any reflection/instantiation step in constructing the root command line fails, getCommandsWithoutRoot wraps the failure in a RuntimeException('Failed to initialize command line hierarchy'). This is an initialization failure of the CLI itself, before any command runs.

Source

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

        }
    }

    public static File getHistoryFile()
    {
        return new File(FBUtilities.getToolsOutputDirectory(), HISTORYFILE);
    }

    public static List<String> getCommandsWithoutRoot(String separator)
    {
        List<String> commands = new ArrayList<>();
        try
        {
            getCommandsWithoutRoot(createCommandLine(new CassandraCliFactory(new NodeProbeFactory(), Output.CONSOLE)), commands, separator);
            return commands;
        }
        catch (Exception e)
        {
            throw new RuntimeException("Failed to initialize command line hierarchy", e);
        }
    }

    private static void getCommandsWithoutRoot(CommandLine cli, List<String> commands, String separator)
    {
        String name = cli.getCommandSpec().qualifiedName(separator);
        // Skip the root command as it's not a real command.
        if (cli.getCommandSpec().root() != cli.getCommandSpec())
            commands.add(name.replace(cli.getCommandSpec().root().qualifiedName() + separator, ""));
        for (CommandLine sub : cli.getSubcommands().values())
            getCommandsWithoutRoot(sub, commands, separator);
    }

    public static CommandLine createCommandLine(CommandLine.IFactory factory) throws Exception
    {
        return new CommandLine(new NodetoolCommand(), factory)
                   .addMixin(JmxConnect.MIXIN_KEY, factory.create(JmxConnect.class));
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Inspect the exception cause (stack trace below the message) for the failing command class.
2. Rebuild/reinstall Cassandra so the nodetool jar and its dependencies are consistent (use .build/build-jars.sh or official distribution).
3. Run with a supported Java version for the node's Cassandra release (Java 11/17/21 per release).
4. Ensure no stale jars/classes shadow the official tools on the classpath.

Example fix

// before
nodetool status   // RuntimeException: Failed to initialize command line hierarchy
// after
# rebuild from a clean checkout
.build/build-jars.sh -s --clean && bin/nodetool status

try { NodeTool.main(args); }
catch (RuntimeException e) { if (e.getMessage().startsWith("Failed to initialize command line hierarchy")) { e.getCause().printStackTrace(); /* check jar/Java version */ } }

When it happens

Trigger: Launching nodetool when a command class cannot be instantiated/reflectively resolved — e.g. corrupted jar, classpath problems, incompatible NodeProbeFactory, or an exception thrown inside a command's constructor/initializer.

Common situations: Broken or partial Cassandra installation; mixing jar versions on the classpath; running nodetool against an incompatible Java version; packaging errors after custom builds.

Related errors

• Failed to create instance of
• No JmxConnect command found in the top-level hierarchy
• Unknown CLI layout:
• Either --node or --ip needs to be set
• Only one of --node or --ip need to be set

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