apache/cassandra · critical · ConfigurationException

Unable to find class

Error message

Unable to find class <class_name> in packages [<searchPackages>]

What it means

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.

Solutions

  1. Use the fully-qualified class name (package included) so no package search is needed.
  2. Ensure the JAR containing the class is on the classpath of every node.
  3. Fix typos or update the class name for the current Cassandra version.
  4. Check the listed searchPackages in the message to see where the resolver looked.

Example fix

// before (cassandra.yaml)
authenticator:
  class_name: MyAuth  # not in search packages
// after
authenticator:
  class_name: com.example.auth.MyAuth
Defensive patterns

Strategy: try-catch

Validate before calling

String fqcn = name.contains(".") ? name : searchPackages.stream().map(p -> p + "." + name).filter(this::onClasspath).findFirst().orElse(null);
if (fqcn == null) throw new ConfigurationException("class not found: " + name);

Try / catch

try { ParameterizedClass.newInstance(def, expectedType, packages); } catch (ConfigurationException e) { LOG.error("cannot resolve class {}: {}", def.class_name, e.getMessage()); throw e; }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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

Appendix: source

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

                if (!searchPackage.isEmpty() && !searchPackage.endsWith("."))
                    searchPackage = searchPackage + '.';
                String name = searchPackage + parameterizedClass.class_name;
                // Load without initialization so a wrong class name does not run its static initializer here. The
                // type is verified below (once the search has resolved a class) and the class is only initialized
                // later, when it is constructed.
                providerClass = Class.forName(name, false, ParameterizedClass.class.getClassLoader());
            }
            catch (ClassNotFoundException | NoClassDefFoundError e)
            {
                //no-op
            }
        }

        if (providerClass == null)
        {
            String pkgList = '[' + searchPackages.stream().map(p -> '"' + p + '"').collect(Collectors.joining(",")) + ']';
            String error = "Unable to find class " + parameterizedClass.class_name + " in packages " + pkgList;
            throw new ConfigurationException(error);
        }

        // Verify the resolved class is the expected extension type before it is initialized/instantiated. Done once,
        // after the package search, so a wrong-type match under an earlier search package does not abort the search
        // before a valid class under a later package is found.
        if (expectedType != null && !expectedType.isAssignableFrom(providerClass))
            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)

View on GitHub (pinned to 88fd0f6a0e)