apache/cassandra · error · ConfigurationException

Unable to initialize analyzer class option specified [%s]

Error message

Unable to initialize analyzer class option specified [%s]

What it means

IndexMode.validateAnalyzer instantiates the user-specified SASI analyzer class reflectively; if newInstance throws InstantiationException or IllegalAccessException (abstract class, no no-arg constructor, non-public class), the failure is rethrown as a ConfigurationException with this message naming the class.

Source

Thrown at src/java/org/apache/cassandra/index/sasi/conf/IndexMode.java:115

    public static void validateAnalyzer(Map<String, String> indexOptions, ColumnMetadata cd) throws ConfigurationException
    {
        // validate that a valid analyzer class was provided if specified
        if (indexOptions.containsKey(INDEX_ANALYZER_CLASS_OPTION))
        {
            Class<? extends AbstractAnalyzer> analyzerClass = FBUtilities.classForNameWithoutInitialization(indexOptions.get(INDEX_ANALYZER_CLASS_OPTION),
                                                                                                            "analyzer",
                                                                                                            AbstractAnalyzer.class);

            AbstractAnalyzer analyzer;
            try
            {
                analyzer = analyzerClass.newInstance();
                analyzer.validate(indexOptions, cd);
            }
            catch (InstantiationException | IllegalAccessException e)
            {
                throw new ConfigurationException(String.format("Unable to initialize analyzer class option specified [%s]",
                                                               analyzerClass.getSimpleName()));
            }
        }
    }

    public static IndexMode getMode(ColumnMetadata column, Optional<IndexMetadata> config) throws ConfigurationException
    {
        return getMode(column, config.isPresent() ? config.get().options : null);
    }

    public static IndexMode getMode(ColumnMetadata column, Map<String, String> indexOptions) throws ConfigurationException
    {
        if (indexOptions == null || indexOptions.isEmpty())
            return IndexMode.NOT_INDEXED;

        Mode mode;

        try

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Make the analyzer class public, concrete, with a public no-arg constructor
2. Ship the analyzer class in the Cassandra classpath (custom jar)
3. Use a built-in analyzer (NonTokenizingAnalyzer, StandardAnalyzer, DelimiterAnalyzer) instead

Example fix

// before
class MyAnalyzer extends AbstractAnalyzer { MyAnalyzer(int x) {...} }
// after
public class MyAnalyzer extends AbstractAnalyzer { public MyAnalyzer() {...} }

Class<?> c = Class.forName(analyzerClassName);
if (Modifier.isAbstract(c.getModifiers()) || Modifier.isInterface(c.getModifiers())
    || !Modifier.isPublic(c.getModifiers())
    || java.util.Arrays.stream(c.getConstructors()).noneMatch(ctor -> ctor.getParameterCount() == 0 && Modifier.isPublic(ctor.getModifiers())))
  throw new ConfigurationException("Analyzer class must be public, concrete, with a public no-arg constructor: " + analyzerClassName);

try { session.execute(createIndexCql); } catch (ConfigurationException e) { if (e.getMessage().startsWith("Unable to initialize analyzer class")) { log.error("Check analyzer class: public, concrete, no-arg constructor, on server classpath", e); } throw e; }

When it happens

Trigger: Creating a SASI index with 'analyzer_class' pointing to a class that cannot be instantiated: abstract, interface, no public no-arg constructor, or not public.

Common situations: Typo'd or fully custom analyzer classes lacking a public no-arg constructor; deploying a custom analyzer not on the server classpath (leading instead to ClassNotFoundException earlier); inner classes not declared static.

Related errors

• Failed to instantiate %s
• No readable property '%s' on class: %s
• Unable to find getter for property '%s' on class %s
• No valid constructor found for class <class_name>
• Unable to instantiate parameterized class <class_name>

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