apache/cassandra · error

error: {message}

Error message

error: {message}

What it means

OfflineClusterMetadataDump.main registers picocli's execution exception handler that calls err(ex), printing 'error: <message>' plus the stack trace to stderr and returning exit code 2. Any exception thrown while executing the offline metadata dump command surfaces through this handler.

Source

Thrown at src/java/org/apache/cassandra/tools/OfflineClusterMetadataDump.java:107

 *
 * # Dump distributed log (CMS nodes)
 * offlineclustermetadatadump distributed-log --data-dir /path/to/data
 * </pre>
 */
@Command(name = "offlineclustermetadatadump",
mixinStandardHelpOptions = true,
description = "Offline tool to dump cluster metadata from local SSTables. NOTE: For offline use only.",
subcommands = { OfflineClusterMetadataDump.MetadataCommand.class, OfflineClusterMetadataDump.LogCommand.class, OfflineClusterMetadataDump.DistributedLogCommand.class })
public class OfflineClusterMetadataDump implements Runnable
{
    private static final Output output = Output.CONSOLE;

    public static void main(String... args)
    {
        Util.initDatabaseDescriptor();

        CommandLine cli = new CommandLine(OfflineClusterMetadataDump.class).setExecutionExceptionHandler((ex, cmd, parseResult) -> {
            err(ex);
            return 2;
        });
        int status = cli.execute(args);
        System.exit(status);
    }

    protected static void err(Throwable e)
    {
        output.err.println("error: " + e.getMessage());
        output.err.println("-- StackTrace --");
        output.err.println(getStackTraceAsString(e));
    }

    @Override
    public void run()
    {
        CommandLine.usage(this, output.out);
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Inspect the '-- StackTrace --' section printed after the error line to find the root cause
2. Verify the target directories/files exist and belong to the same Cassandra version
3. Run with correct arguments: check 'offlinectools' usage for the dump subcommand's required options
4. Ensure Util.initDatabaseDescriptor() prerequisites are met (cassandra.yaml readable, config valid)

Example fix

// before
OfflineClusterMetadataDump dumpMainArgs = new OfflineClusterMetadataDump(Paths.get("/wrong/path"));
// after
Path p = Paths.get("/var/lib/cassandra/data");
if (!Files.isDirectory(p)) throw new IllegalArgumentException("not a directory: " + p);
OfflineClusterMetadataDump dumpMainArgs = new OfflineClusterMetadataDump(p);

// validate inputs before invoking the offline dump
Path dir = Paths.get(dataDir);
if (!Files.isDirectory(dir))
    throw new IllegalArgumentException("data directory does not exist: " + dir);
if (!Files.isReadable(dir))
    throw new IllegalArgumentException("data directory not readable: " + dir);

try {
    int status = cli.execute(args);
    System.exit(status);
} catch (Throwable t) {
    t.printStackTrace();
    System.exit(2);
}

When it happens

Trigger: cli.execute(args) runs the dump command and an exception occurs: unreadable or corrupt metadata files (hoststats/metadata dump paths), invalid command-line options causing execution failure, or Schema/DatabaseDescriptor initialization problems.

Common situations: Running the dump against SSTables/metadata from a mismatched Cassandra version; missing or unreadable data/hints directories; running without the required environment (JAVA_HOME, cassandra config) so Util.initDatabaseDescriptor fails.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• Failed to initialize command line hierarchy
• Unknown keyspace/table %s.%s
• Either --sstables or --journal-segments must be provided
• Unknown keyspace/table %s.%s
• Unknown keyspace %s

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