apache/cassandra · critical · ConfigurationException

Missing value for commitlog_sync_period.

Error message

Missing value for commitlog_sync_period.

What it means

For periodic (default) commitlog sync, commitlog_sync_period_in_ms defines how often the commitlog is fsynced. applySimpleConfig uses a 0ms period as the sentinel for 'unset' and throws at startup, refusing to run periodic sync with no period configured.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:665

            logger.debug("Syncing log with batch mode");
        }
        else if (conf.commitlog_sync == CommitLogSync.group)
        {
            if (conf.commitlog_sync_group_window.toMilliseconds() == 0)
            {
                throw new ConfigurationException("Missing value for commitlog_sync_group_window.", false);
            }
            else if (conf.commitlog_sync_period.toMilliseconds() != 0)
            {
                throw new ConfigurationException("Group sync specified, but commitlog_sync_period found. Only specify commitlog_sync_group_window when using group sync", false);
            }
            logger.debug("Syncing log with a group window of {}", conf.commitlog_sync_period.toString());
        }
        else
        {
            if (conf.commitlog_sync_period.toMilliseconds() == 0)
            {
                throw new ConfigurationException("Missing value for commitlog_sync_period.", false);
            }
            logger.debug("Syncing log with a period of {}", conf.commitlog_sync_period.toString());
        }

        if (conf.accord.journal.flushPeriod == null)
        {
            conf.accord.journal.flushPeriod = conf.commitlog_sync_period;
            if (conf.accord.journal.flushMode == PERIODIC && conf.commitlog_sync_period.toMilliseconds() == 0)
            {
                logger.warn("Accord journal is configured in periodic mode, while Cassandra commit log is configured in {} mode", conf.commitlog_sync);
                conf.accord.journal.flushPeriod = conf.accord.journal.periodicFlushLagBlock;
            }
        }

        if (conf.accord.durability_flush_interval == null)
            conf.accord.durability_flush_interval = conf.accord.shard_durability_cycle;

        /* evaluate the DiskAccessMode Config directive, which also affects indexAccessMode selection */

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add `commitlog_sync_period_in_ms: 10000` (the shipped default) to cassandra.yaml.
2. Remove the explicit `commitlog_sync: periodic` line so defaults apply.
3. Use a different sync mode (group with its window) if periodic tuning isn't desired.

Example fix

// before (cassandra.yaml)
commitlog_sync: periodic
commitlog_sync_period_in_ms: 0
// after (cassandra.yaml)
commitlog_sync: periodic
commitlog_sync_period_in_ms: 10000

// Java, before toolInitialization()
var raw = Config.getRawConfig();
boolean periodic = raw == null || raw.commitlog_sync == null || raw.commitlog_sync == CommitLogSync.periodic;
if (periodic && (raw == null || raw.commitlog_sync_period == null || raw.commitlog_sync_period.toMilliseconds() == 0))
    throw new IllegalArgumentException("periodic commitlog_sync requires a non-zero commitlog_sync_period_in_ms");

When it happens

Trigger: commitlog_sync is periodic (explicitly or by default) but `commitlog_sync_period_in_ms` is absent or explicitly 0, evaluated in DatabaseDescriptor.applySimpleConfig during toolInitialization/applyAll.

Common situations: Hand-written minimal cassandra.yaml where the period was omitted; upgrading from a config that relied on defaults but that also pinned commitlog_sync: periodic; automated tools writing commitlog_sync_period_in_ms: 0 to 'disable' syncing.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Missing value for commitlog_sync_group_window.
• Missing required directive CommitLogSync
• Group sync specified, but commitlog_sync_period found. Only
• concurrent_reads must be at least 2, but was ${conf.concurre
• concurrent_writes must be at least 2, but was ${conf.concurr

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