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.

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
• Abbreviated subcommands are not allowed.
• argument for sort must be one of
• argument for top must be a positive integer.

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

Appendix: 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)