apache/cassandra · error · IllegalArgumentException

Bad configuration; unable to start server:

Error message

Bad configuration; unable to start server: 

What it means

DatabaseDescriptor.applyAll wraps any ConfigurationException from config validation into an IllegalArgumentException with the prefix 'Bad configuration; unable to start server: '. It is a catch-all indicating invalid cassandra.yaml settings prevented daemon startup; the underlying ConfigurationException message is appended.

Solutions

1. Read the appended ConfigurationException message after the colon for the real cause
2. Validate cassandra.yaml against the current version's expected keys
3. Fix the offending configuration value and restart
4. Check cassandra version upgrade notes for renamed/removed config keys

Example fix

// before
concurrent_reads: -1
// after
concurrent_reads: 32

// Pre-validate critical config keys before DatabaseDescriptor.applyAll
checkNotNull(yaml.get("data_file_directories"), "data_file_directories");
checkNotNull(yaml.get("commitlog_directory"), "commitlog_directory");

try { DatabaseDescriptor.daemonInitialize(); }
catch (IllegalArgumentException e) {
    // cause message after 'Bad configuration; unable to start server: ' is the real reason
    logger.error("Config error: {}", e.getMessage().replaceFirst(".*: ", ""));
}

When it happens

Trigger: Any invalid configuration caught during daemon init: null required directories, invalid concurrency values, bad endpoint/snitch settings, invalid partitioner, etc.

Common situations: Typos or invalid values in cassandra.yaml; config edited between restarts; automated provisioning writing bad keys.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• accord.journal_directory must not be the same as the…
• accord.working_set_size option was set incorrectly to
• cdc_raw_directory must be specified
• 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/3351620ffc72391f. Report an issue: GitHub.

Appendix: source

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

            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);
        }
    }

    public static IPartitioner getPartitioner()
    {
        return partitioner;
    }

    public static String getPartitionerName()
    {
        return partitionerName;
    }

    /* For tests ONLY, don't use otherwise or all hell will break loose. Tests should restore value at the end. */

View on GitHub (pinned to 88fd0f6a0e)