apache/cassandra · error · ConfigurationException

Exception occured while initializing disk error handler of…

Error message

Exception occured while initializing disk error handler of class %s

What it means

DiskErrorsHandlerService.set() instantiates and installs a custom disk-error handler class (configured via cassandra.disk_error_handler / disk_failure_policy plumbing). If constructing or initializing the new handler throws, the service wraps the cause in a ConfigurationException with this message, naming the offending handler class.

Solutions

1. Fix the disk_error_handler class name in cassandra.yaml to a valid implementation of DiskErrorsHandler
2. Ensure the custom handler class exists on the classpath and has an accessible constructor
3. Check the wrapped cause (ConfigurationException's initCause) for the real instantiation failure
4. Revert to the default handler (remove the custom config) to restore startup

Example fix

// before (cassandra.yaml)
disk_error_handler: com.example.BadHandler
// after
disk_error_handler: com.example.MyDiskErrorHandler  // present on classpath, implements DiskErrorsHandler

// before startup, validate the configured handler class
String cls = DatabaseDescriptor.getRawConfig().disk_error_handler;
if (cls != null) {
    try {
        Class<?> c = Class.forName(cls);
        if (!DiskErrorsHandler.class.isAssignableFrom(c))
            throw new IllegalArgumentException(cls + " does not implement DiskErrorsHandler");
        c.getDeclaredConstructor().setAccessible(true); // fails fast if no usable constructor
    } catch (ReflectiveOperationException e) {
        throw new IllegalStateException("Bad disk_error_handler config: " + cls, e);
    }
}

boolean isValidDiskErrorHandler(String className) {
    try {
        return Class.forName(className) instanceof Class<?> c
            && DiskErrorsHandler.class.isAssignableFrom(c);
    } catch (ClassNotFoundException e) { return false; }
}

try {
    DiskErrorsHandlerService.set(configuredHandlerClass);
} catch (ConfigurationException e) {
    logger.error("Failed to init disk error handler {}: {}", e.getMessage(), e.getCause(), e);
    DiskErrorsHandlerService.set(DefaultDiskErrorHandler.class.getName()); // fall back to default
}

When it happens

Trigger: set() is called with a handler class whose constructor/initialization throws — e.g. bad class name, missing no-arg constructor, class not on classpath, or the handler's own init fails on the current configuration.

Common situations: Typo in cassandra.disk_error_handler class name in cassandra.yaml; custom handler class not packaged on the classpath; handler incompatible with the Cassandra version after upgrade.

Related errors

• Can not initialize CMS without any seeds
• Cannot find configured row cache provider class
• Cannot locate . If this is a local file, please confirm…
• Cannot replace a live node...
• Cannot replace same address when accord transactions are…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/DiskErrorsHandlerService.java:63

        try
        {
            newInstance.init();
            instance = newInstance;

            try
            {
                oldInstance.close();
            }
            catch (Throwable t)
            {
                logger.warn("Exception occured while closing disk error handler of class " + oldInstance.getClass().getName(), t);
            }
        }
        catch (Throwable t)
        {
            throw new ConfigurationException("Exception occured while initializing disk error handler of class " + newInstance.getClass().getName(), t);
        }
    }

    public static DiskErrorsHandler get()
    {
        return instance;
    }

    public static void close() throws Throwable
    {
        get().close();
    }

    public static void configure() throws ConfigurationException
    {
        String fsErrorHandlerClass = CassandraRelevantProperties.CUSTOM_DISK_ERROR_HANDLER.getString();
        DiskErrorsHandler fsErrorHandler = fsErrorHandlerClass == null
                                           ? new DefaultDiskErrorsHandler()
                                           : FBUtilities.construct(fsErrorHandlerClass, "disk error handler", DiskErrorsHandler.class);

View on GitHub (pinned to 88fd0f6a0e)