apache/cassandra · error · IllegalStateException

Unknown CLI layout:

Error message

Unknown CLI layout: 

What it means

NodeTool.configureCliLayout switches on a CliLayout enum to set up help/usage formatting. The default branch throws an IllegalStateException('Unknown CLI layout: ' + layout) — meaning the configured layout value is not one of the supported variants (e.g. the DEFAULT/CASSANDRA and PICOCLI layouts). Since enums normally prevent this, it usually arises from a new enum constant added without a corresponding case, or a deserialized/foreign enum value.

Source

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

    private static void configureCliLayout(CommandLine commandLine)
    {
        CliLayout defaultLayout = CliLayout.valueOf(toUpperCaseLocalized(CassandraRelevantProperties.CASSANDRA_CLI_LAYOUT.getDefaultValue()));
        CliLayout layoutEnv = CassandraRelevantEnv.CASSANDRA_CLI_LAYOUT.getEnum(true, CliLayout.class,
                                                                                CassandraRelevantProperties.CASSANDRA_CLI_LAYOUT.getDefaultValue());
        CliLayout layoutSys = CassandraRelevantProperties.CASSANDRA_CLI_LAYOUT.getEnum(true, CliLayout.class);
        CliLayout layout = layoutEnv != defaultLayout ? layoutEnv : layoutSys;

        switch (layout)
        {
            case AIRLINE:
                commandLine.setHelpFactory(CassandraCliHelpLayout::new)
                           .setUsageHelpWidth(CassandraCliHelpLayout.DEFAULT_USAGE_HELP_WIDTH)
                           .setHelpSectionKeys(CassandraCliHelpLayout.cassandraHelpSectionKeys());
                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));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add a case (or intentionally rely on the default behavior) for the missing CliLayout constant in configureCliLayout.
2. Verify the CliLayout enum and NodeTool classes come from the same build/version.
3. Rebuild the project cleanly so enum and switch definitions are consistent.
4. If this is a stock build, report the mismatch and fall back to the default layout configuration.

Example fix

// before
switch (layout) {
    case DEFAULT_CASSANDRA: ... break;
    case PICOCLI: break;
    default: throw new IllegalStateException("Unknown CLI layout: " + layout);
}
// after
switch (layout) {
    case DEFAULT_CASSANDRA: ... break;
    case PICOCLI: break;
    case NEW_LAYOUT: configureNewLayout(); break;
    default: throw new IllegalStateException("Unknown CLI layout: " + layout);
}

// guard before use
Objects.requireNonNull(layout, "CLI layout must be set");
if (layout != CliLayout.DEFAULT_CASSANDRA && layout != CliLayout.PICOCLI)
    throw new IllegalStateException("Unsupported CliLayout: " + layout);

try { nodeTool.execute(args); }
catch (IllegalStateException e) { if (e.getMessage().startsWith("Unknown CLI layout")) log.error("Unsupported layout configured: {}", layout); }

When it happens

Trigger: Launching NodeTool when ToolCommand default layout is set to an enum value not handled in the switch — typically a newly added CliLayout constant in a custom/patched build, or code compiled against a different enum version than the running NodeTool class.

Common situations: Custom Cassandra forks adding new CLI layouts without updating configureCliLayout; hot-swapping jars of mixed versions; developers adding an enum constant in a patch without extending the switch.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Timeout type requires one of (read, range, write, counterwri
• Failed to initialize command line hierarchy
• Either --node or --ip needs to be set
• Only one of --node or --ip need to be set
• 'nodetool bootstrap resume' is disabled.

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