{"record":{"id":"f5c3250bac26128d","repo":"apache/cassandra","slug":"unable-to-find-class-class-name-in-packages-se","errorCode":null,"errorMessage":"Unable to find class <class_name> in packages [<searchPackages>]","messagePattern":"Unable to find class <class_name> in packages \\[<searchPackages>\\]","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/config/ParameterizedClass.java","lineNumber":107,"sourceCode":"                if (!searchPackage.isEmpty() && !searchPackage.endsWith(\".\"))\n                    searchPackage = searchPackage + '.';\n                String name = searchPackage + parameterizedClass.class_name;\n                // Load without initialization so a wrong class name does not run its static initializer here. The\n                // type is verified below (once the search has resolved a class) and the class is only initialized\n                // later, when it is constructed.\n                providerClass = Class.forName(name, false, ParameterizedClass.class.getClassLoader());\n            }\n            catch (ClassNotFoundException | NoClassDefFoundError e)\n            {\n                //no-op\n            }\n        }\n\n        if (providerClass == null)\n        {\n            String pkgList = '[' + searchPackages.stream().map(p -> '\"' + p + '\"').collect(Collectors.joining(\",\")) + ']';\n            String error = \"Unable to find class \" + parameterizedClass.class_name + \" in packages \" + pkgList;\n            throw new ConfigurationException(error);\n        }\n\n        // Verify the resolved class is the expected extension type before it is initialized/instantiated. Done once,\n        // after the package search, so a wrong-type match under an earlier search package does not abort the search\n        // before a valid class under a later package is found.\n        if (expectedType != null && !expectedType.isAssignableFrom(providerClass))\n            throw new ConfigurationException(\"Invalid parameterized class \" + providerClass.getName() +\n                                             \": must extend or implement \" + expectedType.getName());\n\n        try\n        {\n            Constructor<?> mapConstructor = filterConstructor(providerClass, c -> c.getParameterTypes().length == 1 && c.getParameterTypes()[0].equals(Map.class));\n            if (mapConstructor != null)\n                return (K) mapConstructor.newInstance(parameterizedClass.parameters == null ? Collections.emptyMap() : parameterizedClass.parameters);\n\n            // Falls-back to no-arg constructor\n            Constructor<?> noArgsConstructor = filterConstructor(providerClass, c -> c.getParameterTypes().length == 0);\n            if (noArgsConstructor != null)","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/ParameterizedClass.java#L89-L125","documentation":"ParameterizedClass.newInstance resolves the configured class_name by searching a set of default/known packages. If no class with that name can be found in any search package, ConfigurationException is thrown listing the searched packages. This is Cassandra's mechanism for shorthand class names in config.","triggerScenarios":"Configuring a parameterized class (e.g. an encryptor, seed provider, auth class) in cassandra.yaml with a class name that doesn't exist in any of the searched packages — typos, removed classes, or custom classes not on the classpath.","commonSituations":"Deploying a custom class without shipping the JAR to all nodes; renaming/moving classes across Cassandra versions; typo'd shorthand names; forgetting fully-qualify a class that isn't in a default search package.","solutions":["Use the fully-qualified class name (package included) so no package search is needed.","Ensure the JAR containing the class is on the classpath of every node.","Fix typos or update the class name for the current Cassandra version.","Check the listed searchPackages in the message to see where the resolver looked."],"exampleFix":"// before (cassandra.yaml)\nauthenticator:\n  class_name: MyAuth  # not in search packages\n// after\nauthenticator:\n  class_name: com.example.auth.MyAuth","handlingStrategy":"try-catch","validationCode":"String fqcn = name.contains(\".\") ? name : searchPackages.stream().map(p -> p + \".\" + name).filter(this::onClasspath).findFirst().orElse(null);\nif (fqcn == null) throw new ConfigurationException(\"class not found: \" + name);","typeGuard":null,"tryCatchPattern":"try { ParameterizedClass.newInstance(def, expectedType, packages); } catch (ConfigurationException e) { LOG.error(\"cannot resolve class {}: {}\", def.class_name, e.getMessage()); throw e; }","preventionTips":["Ship custom class JARs to every node and confirm with Class.forName before restart","Prefer fully-qualified class names in cassandra.yaml","Check class names against the target Cassandra version's search packages","Test config startup on a staging node before rolling out"],"tags":["config","classpath","class-not-found"],"backgroundTag":"class-not-found","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"}