apache/cassandra · critical · ConfigurationException

Missing value for commitlog_sync_group_window.

Error message

Missing value for commitlog_sync_group_window.

What it means

When commitlog_sync is set to CommitLogSync.group, Cassandra requires an explicit commitlog_sync_group_window duration; the config loader defaults the window to 0 milliseconds when unset. DatabaseDescriptor.applySimpleConfig treats a 0ms window as 'not configured' and fails fast at startup with this ConfigurationException rather than running with a zero-length group commit window, which would break group-commit batching.

Source

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

        if (conf.commitlog_sync == null)
        {
            throw new ConfigurationException("Missing required directive CommitLogSync", false);
        }

        if (conf.commitlog_sync == CommitLogSync.batch)
        {
            if (conf.commitlog_sync_period.toMilliseconds() != 0)
            {
                throw new ConfigurationException("Batch sync specified, but commitlog_sync_period found.", false);
            }
            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)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add `commitlog_sync_group_window_in_ms: 1000` (a sensible value, e.g. 100-2000ms) to cassandra.yaml next to commitlog_sync: group.
2. Remove the commitlog_sync override so the default (periodic) sync is used if you don't need group sync.
3. Set a non-zero commitlog_sync_group_window_in_ms in the JVM system properties / Config used for embedded or test initialization before calling toolInitialization().

Example fix

// before (cassandra.yaml)
commitlog_sync: group
// after (cassandra.yaml)
commitlog_sync: group
commitlog_sync_group_window_in_ms: 1000

// Java, before toolInitialization()
if (Config.getRawConfig() != null && Config.getRawConfig().commitlog_sync == CommitLogSync.group
    && (Config.getRawConfig().commitlog_sync_group_window == null
        || Config.getRawConfig().commitlog_sync_group_window.toMilliseconds() == 0))
    throw new IllegalArgumentException("commitlog_sync=group requires a non-zero commitlog_sync_group_window_in_ms");

When it happens

Trigger: Setting `commitlog_sync: group` in cassandra.yaml while omitting `commitlog_sync_group_window_in_ms` (or setting it to 0), then calling DatabaseDescriptor.toolInitialization()/applyAll (i.e., any node startup).

Common situations: Operators switching from periodic/commit sync to group sync following old tuning guides that predate the group window parameter; hand-edited cassandra.yaml copies where the window line was dropped; templated configs that only substitute the sync mode.

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_period.
• 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/a09e2416dc738aeb. Report an issue: GitHub.