apache/cassandra · error · InitializationException

No JmxConnect command found in the top-level hierarchy

Error message

No JmxConnect command found in the top-level hierarchy

What it means

JmxConnect uses picocli's executionStrategy to fetch the top-level command spec via its mixin key; that mixin holds the JmxConnect user object used to drive JMX connections. If the mixin is absent from the parse result's top-level hierarchy the wiring is broken and InitializationException is thrown during command initialization.

Source

Thrown at src/java/org/apache/cassandra/tools/nodetool/JmxConnect.java:93

    @Option(names = { "-pw", "--password" }, description = "Remote jmx agent password", arity = "0..1")
    private String password = EMPTY;

    @Option(names = { "-pwf", "--password-file" }, description = "Path to the JMX password file", arity = "0..1")
    private String passwordFilePath = EMPTY;

    @Inject
    private INodeProbeFactory nodeProbeFactory;

    /**
     * This method is called by picocli and used depending on the execution strategy.
     * @param parseResult The parsed command line.
     * @return The exit code.
     */
    public static int executionStrategy(ParseResult parseResult)
    {
        CommandSpec jmx = parseResult.commandSpec().mixins().get(MIXIN_KEY);
        if (jmx == null)
            throw new InitializationException("No JmxConnect command found in the top-level hierarchy");

        try (JmxConnectionCommandInvoker invoker = new JmxConnectionCommandInvoker((JmxConnect) jmx.userObject()))
        {
            return invoker.execute(parseResult);
        }
        catch (JmxConnectionCommandInvoker.CloseException e)
        {
            jmx.commandLine()
               .getErr()
               .println("Failed to connect to JMX: " + e.getMessage());
            return jmx.commandLine().getExitCodeExceptionMapper().getExitCode(e);
        }
    }

    /**
     * Initialize the JMX connection to the Cassandra node using the provided options.
     */
    @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure the top-level command spec includes the JmxConnect mixin (specMixin with MIXIN_KEY) before running
2. Use the standard nodetool entry point rather than invoking executionStrategy directly with a hand-built ParseResult
3. Pin the picocli version compatible with this Cassandra release

Example fix

// before
new CommandLine(new NodeTool()).execute(args)
// after
CommandLine cmd = new CommandLine(new NodeTool());
cmd.getCommandSpec().addSubcommand("jmx", new JmxConnect());
cmd.execute(args);

// verify the top-level spec carries the mixin before executing
CommandSpec jmx = parseResult.commandSpec().mixins().get("jmxConnect");
if (jmx == null) throw new IllegalStateException("JmxConnect mixin not registered");

try { JmxConnect.executionStrategy(parseResult); } catch (InitializationException e) { /* fix command hierarchy wiring */ }

When it happens

Trigger: Programmatic (embedded) invocation of JmxConnect without registering the mixin spec (setCommandSpec... MIXIN_KEY) on the top-level command; altered picocli command hierarchy in a custom runner.

Common situations: Embedding nodetool's JmxConnect in another tool; upgrading picocli and changing parse behavior; custom main() that builds the CommandLine without the standard spec setup.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Failed to initialize command line hierarchy
• Failed to create instance of
• Abbreviated subcommands are not allowed.
• Unknown subcommand '
• error: {message}

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