apache/cassandra · error · ConfigurationException

Failed to instantiate class <class_name>: <cause.getMessage(

Error message

Failed to instantiate class <class_name>: <cause.getMessage()>

What it means

Thrown when the selected constructor of the configured parameterized class itself threw an exception (InvocationTargetException). The message wraps the underlying cause's message, so the real failure reason comes from the configured class's own constructor code.

Source

Thrown at src/java/org/apache/cassandra/config/ParameterizedClass.java:139

                return (K) mapConstructor.newInstance(parameterizedClass.parameters == null ? Collections.emptyMap() : parameterizedClass.parameters);

            // Falls-back to no-arg constructor
            Constructor<?> noArgsConstructor = filterConstructor(providerClass, c -> c.getParameterTypes().length == 0);
            if (noArgsConstructor != null)
                return (K) noArgsConstructor.newInstance();

            throw new ConfigurationException("No valid constructor found for class " + parameterizedClass.class_name);
        }
        catch (IllegalAccessException | InstantiationException | ExceptionInInitializerError e)
        {
            throw new ConfigurationException("Unable to instantiate parameterized class " + parameterizedClass.class_name, e);
        }
        catch (InvocationTargetException e)
        {
            Throwable cause = e.getCause();
            String error = "Failed to instantiate class " + parameterizedClass.class_name +
                           (cause.getMessage() != null ? ": " + cause.getMessage() : "");
            throw new ConfigurationException(error, cause);
        }
    }

    private static Constructor<?> filterConstructor(Class<?> providerClass, Predicate<Constructor<?>> filter)
    {
        for (Constructor<?> constructor : providerClass.getDeclaredConstructors())
        {
            if (filter.test(constructor))
                return constructor;
        }

        return null;
    }

    @Override
    public boolean equals(Object that)
    {
        return that instanceof ParameterizedClass && equals((ParameterizedClass) that);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Read the wrapped cause message — it is the exception thrown by the class's own constructor
  2. Fix the underlying failure in the configured class's constructor (bad args, missing file, connection failure)
  3. Add defensive validation in the constructor to fail with a clear message
  4. Test the provider class standalone before wiring it into cassandra.yaml

Example fix

// before
public MyProvider() { open(keystorePath); } // NPE if null
// after
public MyProvider() {
    if (keystorePath == null) throw new ConfigurationException("keystore_path must be set");
    open(keystorePath);
}
Defensive patterns

Strategy: try-catch

Validate before calling

// smoke-test the constructor before wiring config
Object o = Class.forName(className).getDeclaredConstructor().newInstance();
assert o != null;

Try / catch

try { K instance = ParameterizedClass.newInstance(cls); }
catch (ConfigurationException e) {
    // e.getCause() is the exception the constructor itself threw
    log.error("Provider {} failed in constructor: {}", className, e.getCause().getMessage(), e);
}

Prevention

When it happens

Trigger: A provider class configured via class_name whose constructor throws at runtime — e.g. fails to read a keystore, connect to KMS, validate parameters, or any other RuntimeException/Error raised during construction.

Common situations: Custom encryption/commitlog providers that open files or network resources in their constructor and fail on bad config; constructor argument validation failures; missing external resources in the deployment environment.

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

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