apache/cassandra · error · IllegalStateException

History file does not exist.%n

Error message

History file %s does not exist.%n

What it means

History.validateHistoryFile checks that the nodetool history file (usually ~/.cassandra/nodetool.history) exists before reading it. If it does not exist, it throws IllegalStateException formatted with the absolute path. The trailing %n produces a newline inside the message.

Solutions

1. Run any nodetool command once with history enabled so the file is created, then retry
2. Check that $HOME is set correctly and ~/.cassandra is writable
3. Verify the expected path printed in the message and point to the right user account
4. If history is intentionally disabled, don't use the history subcommand

Example fix

// before
export HOME=/nonexistent && nodetool history
// after
export HOME=/home/cassandra && nodetool history

# ensure history file exists before running nodetool history
HIST="$HOME/.cassandra/nodetool.history"
[ -f "$HIST" ] || { echo "history file missing at $HIST"; exit 1; }

try { runNodetool("history"); } catch (IllegalStateException e) {
    if (e.getMessage().contains("does not exist")) { log("No nodetool history recorded yet"); return; }
    throw e;
}

When it happens

Trigger: Running `nodetool history` when no history file has ever been written (history logging disabled, HOME not set correctly, or the file was deleted).

Common situations: Fresh user accounts or CI containers where nodetool has never been run interactively; HOME pointing elsewhere so nodetool looks in the wrong directory; history disabled via nodetool.settings.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• History file is not a file.%n
• History file is not readable.%n
• argument for sort must be one of
• argument for top must be a positive integer.
• arguments for -F are json,yaml only.

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tools/nodetool/History.java:88

        if (commands > size)
            commandLines = historyCommands;
        else
            commandLines = historyCommands.subList(size - commands, size);

        return commandLines;
    }

    /**
     * Nodetool is appending command to history file before it is executed so us checking on its
     * existence and validating it is not technically necessary however nodetool is also swallowing
     * all errors when it was not succesful in appending to the history file so better to check here in that case.
     *
     * @param historyFile file to check that it is actually a file which exists and it is readable
     */
    void validateHistoryFile(File historyFile)
    {
        if (!historyFile.exists())
            throw new IllegalStateException(String.format("History file %s does not exist.%n", historyFile.absolutePath()));

        if (!historyFile.isFile())
            throw new IllegalStateException(String.format("History file %s is not a file.%n", historyFile.absolutePath()));

        if (!historyFile.isReadable())
            throw new IllegalStateException(String.format("History file %s is not readable.%n", historyFile.absolutePath()));
    }
}

View on GitHub (pinned to 88fd0f6a0e)