{"record":{"id":"1db173c93aa6b0ba","repo":"apache/cassandra","slug":"exception-occured-while-initializing-disk-error-ha-1db173","errorCode":null,"errorMessage":"Exception occured while initializing disk error handler of class %s","messagePattern":"Exception occured while initializing disk error handler of class (.+?)","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/service/DiskErrorsHandlerService.java","lineNumber":63,"sourceCode":"\n        try\n        {\n            newInstance.init();\n            instance = newInstance;\n\n            try\n            {\n                oldInstance.close();\n            }\n            catch (Throwable t)\n            {\n                logger.warn(\"Exception occured while closing disk error handler of class \" + oldInstance.getClass().getName(), t);\n            }\n        }\n        catch (Throwable t)\n        {\n            throw new ConfigurationException(\"Exception occured while initializing disk error handler of class \" + newInstance.getClass().getName(), t);\n        }\n    }\n\n    public static DiskErrorsHandler get()\n    {\n        return instance;\n    }\n\n    public static void close() throws Throwable\n    {\n        get().close();\n    }\n\n    public static void configure() throws ConfigurationException\n    {\n        String fsErrorHandlerClass = CassandraRelevantProperties.CUSTOM_DISK_ERROR_HANDLER.getString();\n        DiskErrorsHandler fsErrorHandler = fsErrorHandlerClass == null\n                                           ? new DefaultDiskErrorsHandler()\n                                           : FBUtilities.construct(fsErrorHandlerClass, \"disk error handler\", DiskErrorsHandler.class);","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/DiskErrorsHandlerService.java#L45-L81","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the disk_error_handler class name in cassandra.yaml to a valid implementation of DiskErrorsHandler","Ensure the custom handler class exists on the classpath and has an accessible constructor","Check the wrapped cause (ConfigurationException's initCause) for the real instantiation failure","Revert to the default handler (remove the custom config) to restore startup"],"exampleFix":"// before (cassandra.yaml)\ndisk_error_handler: com.example.BadHandler\n// after\ndisk_error_handler: com.example.MyDiskErrorHandler  // present on classpath, implements DiskErrorsHandler","handlingStrategy":"validation","validationCode":"// before startup, validate the configured handler class\nString cls = DatabaseDescriptor.getRawConfig().disk_error_handler;\nif (cls != null) {\n    try {\n        Class<?> c = Class.forName(cls);\n        if (!DiskErrorsHandler.class.isAssignableFrom(c))\n            throw new IllegalArgumentException(cls + \" does not implement DiskErrorsHandler\");\n        c.getDeclaredConstructor().setAccessible(true); // fails fast if no usable constructor\n    } catch (ReflectiveOperationException e) {\n        throw new IllegalStateException(\"Bad disk_error_handler config: \" + cls, e);\n    }\n}","typeGuard":"boolean isValidDiskErrorHandler(String className) {\n    try {\n        return Class.forName(className) instanceof Class<?> c\n            && DiskErrorsHandler.class.isAssignableFrom(c);\n    } catch (ClassNotFoundException e) { return false; }\n}","tryCatchPattern":"try {\n    DiskErrorsHandlerService.set(configuredHandlerClass);\n} catch (ConfigurationException e) {\n    logger.error(\"Failed to init disk error handler {}: {}\", e.getMessage(), e.getCause(), e);\n    DiskErrorsHandlerService.set(DefaultDiskErrorHandler.class.getName()); // fall back to default\n}","preventionTips":["Fully qualify the handler class name in cassandra.yaml and verify it implements DiskErrorsHandler","Ship the custom handler on the classpath (lib/ or a fat jar) and smoke-test class loading before rollout","Read e.getCause() of the ConfigurationException — it names the real constructor/init failure","After version upgrades, re-verify custom handler compatibility with DiskErrorsHandler API"],"tags":["configuration","disk-error-handler","startup","init"],"backgroundTag":"module-init-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}