apache/cassandra · error · ConfigurationException

Failed to instantiate %s

Error message

Failed to instantiate %s

What it means

authInstantiate wraps InstantiationException/IllegalAccessException from reflective instantiation of the configured authenticator/authorizer/role manager/network authorizer/default role initializer class into ConfigurationException('Failed to instantiate <class>'). This means the class was found but could not be constructed reflectively — typically it has no public no-arg constructor, is abstract, or is an interface.

Source

Thrown at src/java/org/apache/cassandra/auth/AuthConfig.java:188

    {
        if (authCls != null && authCls.class_name != null)
        {
            String authPackage = AuthConfig.class.getPackage().getName();
            return ParameterizedClass.newInstance(authCls, List.of("", authPackage), expectedType);
        }

        if (defaultCls == null)
            return null;

        // for now, this has to stay and can not be replaced by ParameterizedClass.newInstance as above
        // due to that failing for simulator dtests. See CASSANDRA-20450 for more information.
        try
        {
            return defaultCls.newInstance();
        }
        catch (InstantiationException | IllegalAccessException  e)
        {
            throw new ConfigurationException("Failed to instantiate " + defaultCls.getName(), e);
        }
    }

    private static <T> T authInstantiate(ParameterizedClass authCls, Class<T> expectedType, T defaultInstance)
    {
        if (authCls != null && authCls.class_name != null)
        {
            String authPackage = AuthConfig.class.getPackage().getName();
            return ParameterizedClass.newInstance(authCls, List.of("", authPackage), expectedType);
        }
        return defaultInstance;
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure the configured class is concrete and has a public no-argument constructor.
2. Check the wrapped cause 'Caused by' in the startup log to identify the exact construction failure.
3. Point the config option at the correct implementation class, not an interface or abstract class.
4. Fix any initialization logic in the plugin's constructor that prevents instantiation.

Example fix

// before
public class MyAuthenticator implements IAuthenticator {
    public MyAuthenticator(String requiredArg) { ... } // no no-arg ctor
}
// after
public class MyAuthenticator implements IAuthenticator {
    public MyAuthenticator() { ... }
}

Class<?> cls = Class.forName(className);
if (cls.isInterface() || java.lang.reflect.Modifier.isAbstract(cls.getModifiers()))
    throw new IllegalArgumentException(className + " is not concrete");
cls.getDeclaredConstructor(); // must exist and be public

boolean isInstantiable(Class<?> c) {
    return !c.isInterface() && !java.lang.reflect.Modifier.isAbstract(c.getModifiers())
        && java.util.Arrays.stream(c.getConstructors()).anyMatch(k -> k.getParameterCount() == 0);
}

try { startCassandra(); } catch (ConfigurationException e) { log.fatal("Failed to instantiate auth class: " + e.getMessage() + ", cause=" + e.getCause()); }

When it happens

Trigger: Configuring an authenticator/authorizer/role_manager/network_authorizer/cidr_authorizer/default_role_initializer class in cassandra.yaml whose default (no-arg) construction fails via Class.newInstance(): abstract class, interface, private or missing public no-arg constructor.

Common situations: Custom auth plugins that define constructors requiring arguments; typo pointing at an interface or abstract base class; plugin class with initialization logic throwing in a way surfaced as InstantiationException.

Related errors

• %s has authorization enabled which requires %s to enable aut
• %s requires %s
• %s can't be used with %s
• %s does not support %s
• %s requires a non-empty %s parameter

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