apache/cassandra · error · ConfigurationException

Unable to instantiate parameterized class <class_name>

Error message

Unable to instantiate parameterized class <class_name>

What it means

Thrown when reflective instantiation of the configured parameterized class fails with IllegalAccessException, InstantiationException, or ExceptionInInitializerError. The class was found and a constructor selected, but invoking it failed — e.g. the constructor is not accessible, the class is abstract, or its static initializer threw.

Source

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

            throw new ConfigurationException("Invalid parameterized class " + providerClass.getName() +
                                             ": must extend or implement " + expectedType.getName());

        try
        {
            Constructor<?> mapConstructor = filterConstructor(providerClass, c -> c.getParameterTypes().length == 1 && c.getParameterTypes()[0].equals(Map.class));
            if (mapConstructor != null)
                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;
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Make the class and its used constructor public and concrete (non-abstract)
  2. Inspect the cause (attached to this ConfigurationException) for the underlying InstantiationException/ExceptionInInitializerError
  3. Fix any exception thrown in the class's static initializer
  4. Ensure the class is loadable in the Cassandra JVM (correct jar on classpath)

Example fix

// before
class MyProvider implements IProvider { ... } // package-private
// after
public class MyProvider implements IProvider {
    public MyProvider() { ... }
}
Defensive patterns

Strategy: try-catch

Validate before calling

Class<?> c = Class.forName(className);
if (java.lang.reflect.Modifier.isAbstract(c.getModifiers()) || c.isInterface())
    throw new IllegalStateException(className + " must be a concrete public class");

Type guard

static boolean isInstantiable(String className) {
    try {
        Class<?> c = Class.forName(className);
        int m = c.getModifiers();
        return !c.isInterface() && !java.lang.reflect.Modifier.isAbstract(m) && java.lang.reflect.Modifier.isPublic(m);
    } catch (Throwable t) { return false; }
}

Try / catch

try { K instance = ParameterizedClass.newInstance(cls); }
catch (ConfigurationException e) {
    // e.getCause() holds InstantiationException / IllegalAccessException / ExceptionInInitializerError
    log.error("Cannot instantiate {}: {}", className, e.getCause(), e);
}

Prevention

When it happens

Trigger: Configured class_name refers to an abstract class or interface (InstantiationException), a non-public class/constructor without accessibility (IllegalAccessException), or a class whose static init block throws (ExceptionInInitializerError).

Common situations: Custom provider classes written package-private or with private constructors; classes that throw in static initializers due to bad environment or missing dependencies; pointing config at abstract base classes.

Related errors

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