apache/cassandra · error · ConfigurationException

Unable to get startup checks via ServiceLoader. Custom…

Error message

Unable to get startup checks via ServiceLoader. Custom checks will not be triggered.

What it means

Cassandra discovers custom StartupCheck implementations via the Java ServiceLoader mechanism (META-INF/services entries). If the ServiceLoader iteration throws a ServiceConfigurationError while enumerating providers, Cassandra wraps it in a ConfigurationException so startup aborts with a clear message explaining that custom checks were not loaded.

Solutions

1. Fix the class listed in META-INF/services/org.apache.cassandra.service.StartupCheck: ensure it exists on the classpath and has a public no-arg constructor
2. Read the cause (ConfigurationException is chained to the ServiceConfigurationError) to identify the exact load failure
3. Remove or correct the stale provider entry if the custom check is no longer needed
4. Verify the custom check jar is compatible with the running Cassandra version

Example fix

// before (META-INF/services/org.apache.cassandra.service.StartupCheck)
com.example.MyCheck
// class not on classpath -> ServiceConfigurationError
// after: ship the jar containing com.example.MyCheck in lib/ and keep the entry, or delete the line

for each META-INF/services entry, Class.forName(name) in a pre-flight script; fail deploy if ClassNotFoundException or no public no-arg constructor

try { getCustomStartupChecks(); } catch (ConfigurationException e) { logger.error("Custom startup check failed to load", e.getCause()); throw e; }

When it happens

Trigger: A META-INF/services/org.apache.cassandra.service.StartupCheck file references a class that cannot be loaded or instantiated (missing class, constructor throwing, malformed provider file, wrong class name) so ServiceIterator.next throws ServiceConfigurationError during getCustomStartupChecks.

Common situations: Typos in the provider-configuration file, custom check jar missing from the classpath after an upgrade, provider class compiled against a different Cassandra version (NoSuchMethodError/NoClassDefFoundError), a provider constructor that throws.

Related errors

• Can not initialize CMS without any seeds
• Cannot find configured row cache provider class
• Cannot locate . If this is a local file, please confirm…
• Cannot replace a live node...
• Cannot replace same address when accord transactions are…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/StartupChecks.java:182

    public StartupChecks withServiceLoaderTests()
    {
        Set<StartupCheck> customChecks = new HashSet<>();
        Set<String> uniqueNames = new HashSet<>();
        Set<String> duplicitNames = new HashSet<>();

        try
        {
            for (StartupCheck check : ServiceLoader.load(StartupCheck.class))
            {
                if (!uniqueNames.add(check.name()))
                    duplicitNames.add(check.name());
                else
                    customChecks.add(check);
            }
        }
        catch (ServiceConfigurationError t)
        {
            throw new ConfigurationException("Unable to get startup checks via ServiceLoader. " +
                                             "Custom checks will not be triggered.", t);
        }

        if (!duplicitNames.isEmpty())
        {
            throw new IllegalStateException("There was an attempt to load custom startup " +
                                            "checks with same name which is ambiguous: " + duplicitNames);
        }

        for (StartupCheck customCheck : customChecks)
        {
            for (StartupCheck preFlightCheck : preFlightChecks)
            {
                if (preFlightCheck.name().equals(customCheck.name()))
                {
                    throw new IllegalStateException("There was an attempt to load custom startup check " +
                                                    "with same name as in-built check: " + preFlightCheck.name());
                }

View on GitHub (pinned to 88fd0f6a0e)