apache/cassandra · error · RuntimeException

Unable to load commitlog_archiving.properties

Error message

Unable to load commitlog_archiving.properties

What it means

Thrown during CommitLogArchiver construction when the commitlog_archiving.properties file exists but cannot be read (IOException while loading its contents). Cassandra requires this file to be parseable when it is present, since it defines archive/restore commands. The underlying IOException is chained as the cause.

Source

Thrown at src/java/org/apache/cassandra/db/commitlog/CommitLogArchiver.java:120

    public static CommitLogArchiver construct()
    {
        Properties commitlogProperties = new Properties();
        try (InputStream stream = CommitLogArchiver.class.getClassLoader().getResourceAsStream(COMMITLOG_ARCHIVNG_PROPERTIES_FILE_NAME))
        {
            if (stream == null)
            {
                logger.trace("No {} found; archiving and point-in-time-restoration will be disabled", COMMITLOG_ARCHIVNG_PROPERTIES_FILE_NAME);
                return disabled();
            }
            else
            {
                commitlogProperties.load(stream);
                return getArchiverFromProperties(commitlogProperties);
            }
        }
        catch (IOException e)
        {
            throw new RuntimeException("Unable to load " + COMMITLOG_ARCHIVNG_PROPERTIES_FILE_NAME, e);
        }
    }

    @VisibleForTesting
    static CommitLogArchiver getArchiverFromProperties(Properties commitlogCommands)
    {
        assert !commitlogCommands.isEmpty();
        String archiveCommand = commitlogCommands.getProperty("archive_command");
        String restoreCommand = commitlogCommands.getProperty("restore_command");
        String restoreDirectories = commitlogCommands.getProperty("restore_directories");
        if (restoreDirectories != null && !restoreDirectories.isEmpty())
        {
            for (String dir : restoreDirectories.split(DELIMITER))
            {
                File directory = new File(dir);
                if (!directory.exists())
                {
                    if (!directory.tryCreateDirectory())

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check file permissions on commitlog_archiving.properties so the Cassandra process can read it (read access for the cassandra user).
2. Verify the file is not empty/corrupted; re-deploy a valid commitlog_archiving.properties.
3. Fix the underlying filesystem issue (disk full, NFS hang) reported in the chained IOException cause.
4. If archiving is not used, either remove the file or leave it present but valid; Cassandra only reads it when it exists.

Example fix

// before (unreadable file)
-rw------- root root /etc/cassandra/commitlog_archiving.properties
// after
chown cassandra:cassandra /etc/cassandra/commitlog_archiving.properties
chmod 644 /etc/cassandra/commitlog_archiving.properties

// before startup
File f = new File(confDir, "commitlog_archiving.properties");
if (f.exists() && (!f.isFile() || !f.canRead()))
    throw new IllegalStateException("commitlog_archiving.properties exists but is not readable");

try { archiver = CommitLogArchiver.construct(); }
catch (RuntimeException e) {
    if (e.getCause() instanceof IOException)
        log.error("Fix commitlog_archiving.properties read access", e);
    throw e;
}

When it happens

Trigger: Calling CommitLogArchiver.construct() when commitlog_archiving.properties exists on the classpath/config path but the read fails (I/O error, unreadable permissions, stream closed mid-read).

Common situations: File permissions changed after deployment; file truncated or corrupted; filesystem errors (NFS, disk full) while reading the properties file; container image with partially copied config.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• commitlog_directory must not be the same as any data_file_di
• local_system_data_file_directory must not be the same as the
• Unable to create directory:
• Unable to parse precision of value
• NANOSECONDS level precision is not supported.

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