apache/cassandra · error · IllegalStateException

There was an attempt to load custom startup check with same…

Error message

There was an attempt to load custom startup check with same name as in-built check: ${preFlightCheck.name()}

What it means

A custom startup check registered via ServiceLoader uses a name() that collides with one of Cassandra's built-in pre-flight checks. Since names identify checks, Cassandra throws IllegalStateException to prevent a custom check from shadowing or being confused with an in-built one.

Solutions

Change the custom check's name() to a unique value not used by built-in checks
Consult the built-in pre-flight check names (in StartupChecks.java) and pick a vendor-prefixed name
Rebuild and redeploy the custom check jar

Example fix

// before
public String name() { return "disk_space"; }
// after
public String name() { return "acme_disk_space"; }

Defensive patterns

Strategy: validation

Validate before calling

compare planned custom check names against built-in check names listed in StartupChecks.java before deploy

Prevention

Always vendor-prefix custom check names
Grep the built-in names when creating a new check
Never copy built-in check templates without renaming

When it happens

Trigger: During getCustomStartupChecks, a custom check's name() equals a built-in preFlightCheck's name() in the nested comparison loop.

Common situations: Naming a custom check 'snapshot' or 'disk_space' etc., colliding with built-ins; copying built-in check source as a template without changing name().

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/bc622ea992db8fef. Report an issue: GitHub.

Appendix: source

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

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

    /**
     * Add system test to be run before schema is loaded during startup
     * @param test the system test to include
     */
    public StartupChecks withTest(StartupCheck test)
    {
        preFlightChecks.add(test);
        return this;

View on GitHub (pinned to 88fd0f6a0e)