apache/cassandra · critical · ConfigurationException

Missing required directive CommitLogSync

Error message

Missing required directive CommitLogSync

What it means

commitlog_sync is a required directive in cassandra.yaml; Cassandra refuses to start if it is unset. The sync mode (periodic, batch, group) determines how writes are acknowledged by the commit log, so it must be explicitly configured.

Solutions

1. Add 'commitlog_sync: periodic' (or 'batch'/'group') to cassandra.yaml
2. When using 'periodic', also set commitlog_sync_period_in_ms; for 'batch' ensure the period is 0/absent
3. Compare against the shipped cassandra.yaml template and restore any missing required directives

Example fix

# before (cassandra.yaml)
# commitlog_sync directive missing
# after
commitlog_sync: periodic
commitlog_sync_period_in_ms: 10000

if (yaml.get("commitlog_sync") == null) throw new IllegalStateException("cassandra.yaml missing required commitlog_sync");

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { log.error("missing required directive: {}", e.getMessage()); System.exit(1); }

When it happens

Trigger: DatabaseDescriptor.applySimpleConfig finds conf.commitlog_sync == null during startup (applyAll) or tool initialization because cassandra.yaml omits the commitlog_sync directive.

Common situations: Minimal/hand-written cassandra.yaml missing the directive, an upgrade where the option was removed from the file, or a template config stripped down too far.

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

• Accord journal is configured in periodic mode, while…
• Batch sync specified, but commitlog_sync_period found.
• Configured " " could not be found
• Configured " " was found, but had no addresses
• Group sync specified, but commitlog_sync_period found. Only…

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

Appendix: source

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

        InetAddressAndPort.initializeDefaultPort(getStoragePort());

        validateUpperBoundStreamingConfig();

        if (conf.auto_snapshot_ttl != null)
        {
            try
            {
                autoSnapshoTtl = new DurationSpec.IntSecondsBound(conf.auto_snapshot_ttl);
            }
            catch (IllegalArgumentException e)
            {
                throw new ConfigurationException("Invalid value of auto_snapshot_ttl: " + conf.auto_snapshot_ttl, false);
            }
        }

        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)
            {

View on GitHub (pinned to 88fd0f6a0e)