{"record":{"id":"325b5ea138a02d52","repo":"apache/cassandra","slug":"failed-to-initialize-command-line-hierarchy","errorCode":null,"errorMessage":"Failed to initialize command line hierarchy","messagePattern":"Failed to initialize command line hierarchy","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/tools/NodeTool.java","lineNumber":182,"sourceCode":"        }\n    }\n\n    public static File getHistoryFile()\n    {\n        return new File(FBUtilities.getToolsOutputDirectory(), HISTORYFILE);\n    }\n\n    public static List<String> getCommandsWithoutRoot(String separator)\n    {\n        List<String> commands = new ArrayList<>();\n        try\n        {\n            getCommandsWithoutRoot(createCommandLine(new CassandraCliFactory(new NodeProbeFactory(), Output.CONSOLE)), commands, separator);\n            return commands;\n        }\n        catch (Exception e)\n        {\n            throw new RuntimeException(\"Failed to initialize command line hierarchy\", e);\n        }\n    }\n\n    private static void getCommandsWithoutRoot(CommandLine cli, List<String> commands, String separator)\n    {\n        String name = cli.getCommandSpec().qualifiedName(separator);\n        // Skip the root command as it's not a real command.\n        if (cli.getCommandSpec().root() != cli.getCommandSpec())\n            commands.add(name.replace(cli.getCommandSpec().root().qualifiedName() + separator, \"\"));\n        for (CommandLine sub : cli.getSubcommands().values())\n            getCommandsWithoutRoot(sub, commands, separator);\n    }\n\n    public static CommandLine createCommandLine(CommandLine.IFactory factory) throws Exception\n    {\n        return new CommandLine(new NodetoolCommand(), factory)\n                   .addMixin(JmxConnect.MIXIN_KEY, factory.create(JmxConnect.class));\n    }","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/tools/NodeTool.java#L164-L200","documentation":"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.","triggerScenarios":"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.","commonSituations":"Broken or partial Cassandra installation; mixing jar versions on the classpath; running nodetool against an incompatible Java version; packaging errors after custom builds.","solutions":["Inspect the exception cause (stack trace below the message) for the failing command class.","Rebuild/reinstall Cassandra so the nodetool jar and its dependencies are consistent (use .build/build-jars.sh or official distribution).","Run with a supported Java version for the node's Cassandra release (Java 11/17/21 per release).","Ensure no stale jars/classes shadow the official tools on the classpath."],"exampleFix":"// before\nnodetool status   // RuntimeException: Failed to initialize command line hierarchy\n// after\n# rebuild from a clean checkout\n.build/build-jars.sh -s --clean && bin/nodetool status","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { NodeTool.main(args); }\ncatch (RuntimeException e) { if (e.getMessage().startsWith(\"Failed to initialize command line hierarchy\")) { e.getCause().printStackTrace(); /* check jar/Java version */ } }","preventionTips":["Run nodetool shipped with the exact Cassandra version in use","Use a supported JDK for the release","Avoid mixing jars on the classpath; verify after custom builds","Report the wrapped cause's stack trace when filing issues"],"tags":["cli","picocli","initialization","nodetool"],"backgroundTag":"module-init-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}