apache/cassandra · error · IllegalStateException

There was an attempt to load custom startup checks with…

Error message

There was an attempt to load custom startup checks with same name which is ambiguous: ${duplicitNames}

What it means

Two or more custom startup checks discovered via ServiceLoader declare the same name() value, which makes check identification ambiguous. Cassandra rejects the configuration with an IllegalStateException rather than silently running duplicate/ambiguous checks.

Solutions

Rename the name() returned by one of the conflicting custom checks
Remove the duplicate provider jar or META-INF/services entry from the classpath
Check the message for the list of duplicated names to find the offenders

Example fix

// before
public String name() { return "disk-check"; }
// after (second provider)
public String name() { return "vendorx-disk-check"; }

Defensive patterns

Strategy: validation

Validate before calling

grep name() returns across all custom check jars and assert uniqueness before deploy

Prevention

Prefix custom check names with a vendor namespace
Audit lib/ for duplicate provider jars
Document check names in an internal registry

When it happens

Trigger: getCustomStartupChecks collects custom checks and two distinct ServiceLoader-provided StartupCheck classes return identical strings from name(), populating duplicitNames.

Common situations: Deploying two different jars that both register a custom check with the same name, copying a custom check and forgetting to rename it, multiple builds of the same provider jar on the classpath.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

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

        preFlightChecks.addAll(customChecks);

        return this;

View on GitHub (pinned to 88fd0f6a0e)