apache/cassandra · error · ConfigurationException

Incorrect index mode: %s

Error message

Incorrect index mode: %s

What it means

IndexMode.getMode parses the 'mode' index option via Mode.mode(), which throws IllegalArgumentException for unknown mode strings. getMode catches it and rethrows a clearer ConfigurationException: 'Incorrect index mode: <value>'.

Source

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

        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
        {
            mode = indexOptions.get(INDEX_MODE_OPTION) == null
                            ? Mode.PREFIX
                            : Mode.mode(indexOptions.get(INDEX_MODE_OPTION));
        }
        catch (IllegalArgumentException e)
        {
            throw new ConfigurationException("Incorrect index mode: " + indexOptions.get(INDEX_MODE_OPTION));
        }

        boolean isAnalyzed = false;
        Class<? extends AbstractAnalyzer> analyzerClass = null;
        if (indexOptions.get(INDEX_ANALYZER_CLASS_OPTION) != null)
        {
            try
            {
                analyzerClass = FBUtilities.classForNameWithoutInitialization(indexOptions.get(INDEX_ANALYZER_CLASS_OPTION),
                                                                              "analyzer",
                                                                              AbstractAnalyzer.class);
                isAnalyzed = indexOptions.get(INDEX_ANALYZED_OPTION) == null
                             ? true : Boolean.parseBoolean(indexOptions.get(INDEX_ANALYZED_OPTION));
            }
            catch (ConfigurationException e)
            {
                if (!(e.getCause() instanceof ClassNotFoundException))
                    throw e;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use one of the valid modes: PREFIX, CONTAINS, or SPARSE (uppercase)
2. Remove the 'mode' option to accept the PREFIX default
3. Validate the mode string against Mode.mode() before creating the index

Example fix

// before
OPTIONS = {'mode': 'FULLTEXT'}
// after
OPTIONS = {'mode': 'CONTAINS'}

Set<String> valid = Set.of("PREFIX", "CONTAINS", "SPARSE");
String mode = options.get("mode");
if (mode != null && !valid.contains(mode)) throw new ConfigurationException("Invalid SASI mode: " + mode + "; expected one of " + valid);

try { session.execute(createIndexCql); } catch (ConfigurationException e) { if (e.getMessage().startsWith("Incorrect index mode")) { options.put("mode", "PREFIX"); session.execute(rebuildCql(options)); } else throw e; }

When it happens

Trigger: CREATE CUSTOM INDEX ... WITH OPTIONS = {'mode': 'FULLTEXT'} or any string other than PREFIX, CONTAINS, SPARSE (case-sensitive); any typo in the mode option value.

Common situations: Typos like 'contains' vs 'CONTAINS', or copying mode names from other search engines (e.g. Elasticsearch) into SASI options.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• case_sensitive option cannot be specified together with eith
• SASI only supports Murmur3Partitioner.
• Only single character delimiters supported, was %s
• Unable to initialize analyzer class option specified [%s]
• Amount of transient nodes should be strictly positive, but w

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