apache/cassandra · error · ConfigurationException

cdc_raw_directory must be specified

Error message

cdc_raw_directory must be specified

What it means

DatabaseDescriptor validates configuration during daemon initialization. When cdc_enabled is true but cdc_raw_directory is not set in cassandra.yaml, it throws a ConfigurationException that is later wrapped as IllegalArgumentException. CDC (Change Data Capture) needs a directory to write raw mutation logs.

Solutions

1. Add cdc_raw_directory: /var/lib/cassandra/cdc_raw to cassandra.yaml
2. Or set cdc_enabled: false if CDC is not needed
3. Or pass the directory via system property -Dcassandra.cdc_raw_directory at startup

Example fix

// before (cassandra.yaml)
cdc_enabled: true
// after
cdc_enabled: true
cdc_raw_directory: /var/lib/cassandra/cdc_raw

Properties yaml = loadYaml("cassandra.yaml");
if (Boolean.parseBoolean(yaml.getProperty("cdc_enabled")) && yaml.getProperty("cdc_raw_directory") == null)
    throw new IllegalStateException("cdc_enabled requires cdc_raw_directory to be set");

When it happens

Trigger: Starting Cassandra with cdc_enabled: true in cassandra.yaml but no cdc_raw_directory defined; programmatically calling DatabaseDescriptor.applyAll/daemonInit with such config.

Common situations: Users enabling CDC in a config file copied from an older version or a minimal template that lacks cdc_raw_directory; config merges dropping the key.

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_directory must not be the same as the…
• accord.working_set_size option was set incorrectly to
• Bad configuration; unable to start server:
• concurrent_reads must be at least 2, but was
• concurrent_writes must be at least 2, but was

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

Appendix: source

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

                throw new ConfigurationException("commitlog_directory must be specified", false);
            FileUtils.createDirectory(conf.commitlog_directory);

            if (conf.accord.journal_directory == null)
                throw new ConfigurationException("accord.journal_directory must be specified", false);
            FileUtils.createDirectory(conf.accord.journal_directory);

            if (conf.hints_directory == null)
                throw new ConfigurationException("hints_directory must be specified", false);
            FileUtils.createDirectory(conf.hints_directory);

            if (conf.saved_caches_directory == null)
                throw new ConfigurationException("saved_caches_directory must be specified", false);
            FileUtils.createDirectory(conf.saved_caches_directory);

            if (conf.cdc_enabled)
            {
                if (conf.cdc_raw_directory == null)
                    throw new ConfigurationException("cdc_raw_directory must be specified", false);
                FileUtils.createDirectory(conf.cdc_raw_directory);
            }

            boolean created = maybeCreateHeapDumpPath();
            if (!created && conf.dump_heap_on_uncaught_exception)
            {
                logger.error(String.format("cassandra.yaml:dump_heap_on_uncaught_exception is enabled but unable to create heap dump path %s. Disabling.", conf.heap_dump_path != null ? conf.heap_dump_path : "null"));
                conf.dump_heap_on_uncaught_exception = false;
            }
        }
        catch (ConfigurationException e)
        {
            throw new IllegalArgumentException("Bad configuration; unable to start server: " + e.getMessage());
        }
        catch (FSWriteError e)
        {
            throw new IllegalStateException(e.getCause().getMessage() + "; unable to start server", e);
        }

View on GitHub (pinned to 88fd0f6a0e)