apache/cassandra · error · ConfigurationException

Invalid configuration of startup_checks:

Error message

Invalid configuration of startup_checks: 

What it means

DatabaseDescriptor failed to construct the StartupChecksConfiguration from the cassandra.yaml startup_checks section. Any throwable while building the default startup checks plus service-loader-supplied tests and applying conf.startup_checks is converted into a ConfigurationException. This means the startup_checks map/list in the config is structurally invalid or references an unusable check.

Solutions

1. Read t.getMessage() appended to the error to identify the offending check entry.
2. Correct or remove the invalid startup_checks entries in cassandra.yaml.
3. Verify any custom startup-check classes are on the classpath and registered for ServiceLoader.
4. Temporarily remove the startup_checks section entirely to confirm it is the source of the failure.

Example fix

// before (cassandra.yaml)
startup_checks:
  - filesystem_ownership_check: disableed
// after
startup_checks:
  - filesystem_ownership_check: disable

// verify every named startup check exists before applying
Map<String, Object> checks = (Map<String, Object>) yaml.get("startup_checks");
if (checks != null) checks.keySet().forEach(k ->
    requireKnownStartupCheck(k)); // throws if not in default/service-loader registry

catch (ConfigurationException e) { logger.error("startup_checks section invalid: {}", e.getMessage()); throw e; }

When it happens

Trigger: cassandra.yaml defines a startup_checks section whose entries (class names, enable/disable flags, parameters) cannot be applied to the StartupChecks object built from withDefaultTests(), FileSystemOwnershipCheck, and withServiceLoaderTests().

Common situations: Disabling a startup check with a misspelled check name; a custom check class on the classpath failing to load via ServiceLoader; merging config files from different Cassandra versions where startup_checks keys differ.

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

• A maximum number of tokens per node is supported
• accord.cache_size option was set incorrectly to
• accord.journal_directory must not be the same as any…
• Allowing java.lang.System.* access in UDFs is dangerous and…
• be positive

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

Appendix: source

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

            throw new ConfigurationException("Invalid configuration for cms_commit_retry_strategy. " + e.getMessage(), e);
        }
    }

    public static StartupChecksConfiguration getStartupChecksConfiguration()
    {
        return startupChecksConfiguration;
    }

    private static void applyStartupChecks()
    {
        try
        {
            StartupChecks startupChecks = new StartupChecks().withDefaultTests().withTest(new FileSystemOwnershipCheck()).withServiceLoaderTests();
            startupChecksConfiguration = new StartupChecksConfiguration(startupChecks, conf.startup_checks);
        }
        catch (Throwable t)
        {
            throw new ConfigurationException("Invalid configuration of startup_checks: " + t.getMessage());
        }
    }

    private static String storagedirFor(String type)
    {
        return storagedir(type + "_directory") + File.pathSeparator() + type;
    }

    private static String storagedir(String errMsgType)
    {
        String storagedir = STORAGE_DIR.getString();
        if (storagedir == null)
            throw new ConfigurationException(errMsgType + " is missing and " + STORAGE_DIR.getKey() + " system property is not set", false);
        return storagedir;
    }

    static int calculateDefaultSpaceInMiB(String type, String path, String setting, int preferredSizeInMiB, long totalSpaceInBytes, long totalSpaceNumerator, long totalSpaceDenominator)
    {

View on GitHub (pinned to 88fd0f6a0e)