apache/cassandra · error · InvalidRequestException

Similarity function was not recognized for index . Valid…

Error message

Similarity function %s was not recognized for index %s. Valid values are: %s

What it means

Thrown by IndexWriterConfig.fromOptions when the 'similarity_function' option value does not match any org.apache.lucene.util.VectorSimilarityFunction enum constant (comparison is on the upper-cased value). Only the Lucene-supported functions (e.g. EUCLIDEAN, COSINE, DOT_PRODUCT) are accepted.

Solutions

1. Use one of the valid values printed in the message (validSimilarityFunctions): EUCLIDEAN, COSINE, DOT_PRODUCT
2. Map your domain term to the Lucene name (e.g. L2 -> EUCLIDEAN, inner_product -> DOT_PRODUCT)
3. Omit the option to use the default similarity function
4. Validate against VectorSimilarityFunction.valueOf(upper(value)) before issuing the DDL

Example fix

// before
WITH OPTIONS = {'similarity_function': 'L2'}
// after
WITH OPTIONS = {'similarity_function': 'EUCLIDEAN'}

String v = opts.get("similarity_function");
if (v != null)
    org.apache.lucene.util.VectorSimilarityFunction.valueOf(v.trim().toUpperCase(java.util.Locale.ROOT)); // throws IllegalArgumentException if invalid

try { session.execute(createIndexCql); }
catch (InvalidRequestException e) {
    if (e.getMessage().contains("was not recognized") && e.getMessage().contains("Similarity function")) { /* map to a valid enum name and retry */ }
    else throw e;
}

When it happens

Trigger: CREATE CUSTOM INDEX on a vector column WITH OPTIONS = {'similarity_function': 'cosine_similarity'} or 'L2' — any name that is not a VectorSimilarityFunction enum constant when upper-cased.

Common situations: Using similarity names from other systems (pgvector 'cosine', 'l2', 'inner_product'); lowercase handled fine, but abbreviations are not; typo like 'EUCLIDEAN_DISTANCE'.

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

• Construction beam width cannot be set without enabling
• Construction beam width for index
• Construction beam width
• Maximum node connections cannot be set without enabling
• Maximum number of connections for index

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

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/IndexWriterConfig.java:163

                }
                catch (NumberFormatException e)
                {
                    throw new InvalidRequestException(String.format("Construction beam width %s is not a valid integer for index %s",
                                                                    options.get(CONSTRUCTION_BEAM_WIDTH), indexName));
                }
                if (queueSize <= 0 || queueSize > MAXIMUM_CONSTRUCTION_BEAM_WIDTH)
                    throw new InvalidRequestException(String.format("Construction beam width for index %s cannot be <= 0 or > %s, was %s", indexName, MAXIMUM_CONSTRUCTION_BEAM_WIDTH, queueSize));
            }
            if (options.containsKey(SIMILARITY_FUNCTION))
            {
                String option = toUpperCaseLocalized(options.get(SIMILARITY_FUNCTION));
                try
                {
                    similarityFunction = VectorSimilarityFunction.valueOf(option);
                }
                catch (IllegalArgumentException e)
                {
                    throw new InvalidRequestException(String.format("Similarity function %s was not recognized for index %s. Valid values are: %s",
                                                                    option, indexName, validSimilarityFunctions));
                }
            }
            if (options.containsKey(OPTIMIZE_FOR))
            {
                String option = toUpperCaseLocalized(options.get(OPTIMIZE_FOR));
                try
                {
                    optimizeFor = OptimizeFor.valueOf(option);
                }
                catch (IllegalArgumentException e)
                {
                    throw new InvalidRequestException(String.format("optimize_for '%s' was not recognized for index %s. Valid values are: %s",
                                                                    option, indexName, validOptimizeFor));
                }
            }
        }
        return new IndexWriterConfig(maximumNodeConnections, queueSize, similarityFunction, optimizeFor);

View on GitHub (pinned to 88fd0f6a0e)