apache/cassandra · error · InvalidRequestException

optimize_for ' ' was not recognized for index . Valid…

Error message

optimize_for '%s' was not recognized for index %s. Valid values are: %s

What it means

SAI (Storage-Attached Index) per-index option 'optimize_for' was given a value that is not one of the recognized enum constants of OptimizeFor. fromOptions parses CREATE CUSTOM INDEX OPTIONS and converts the value with OptimizeFor.valueOf, which throws IllegalArgumentException; it is rethrown as an InvalidRequestException listing the valid values. This protects against silently misconfigured index build options.

Solutions

Use one of the valid values exactly as listed in the error message (case-sensitive enum constant).
Check the OptimizeFor enum in src/java/org/apache/cassandra/index/sai/disk/v1/IndexWriterConfig.java for the constants your version supports.
Remove the optimize_for option entirely to accept the default.

Example fix

// before
CREATE CUSTOM INDEX ON t (c) USING 'StorageAttachedIndex' WITH OPTIONS = {'optimize_for': 'latency'};
// after
CREATE CUSTOM INDEX ON t (c) USING 'StorageAttachedIndex' WITH OPTIONS = {'optimize_for': 'LATENCY'};

Defensive patterns

Strategy: validation

Validate before calling

const VALID_OPTIMIZE_FOR = ['BALANCED','LATENCY','RECALL']; // confirm against your version
if (options.optimize_for && !VALID_OPTIMIZE_FOR.includes(options.optimize_for)) {
  throw new Error(`optimize_for '${options.optimize_for}' invalid; valid: ${VALID_OPTIMIZE_FOR.join(', ')}`);
}

Prevention

Copy option values from the docs of the exact Cassandra version in use.
Keep enum values uppercase and verify case sensitivity.
Test CREATE INDEX DDL in a dev cluster before production.

When it happens

Trigger: CREATE CUSTOM INDEX ... WITH OPTIONS = {'optimize_for': 'xyz'} where 'xyz' is not an OptimizeFor enum constant (valid values are e.g. BALANCED / LATENCY / RECALL, case-sensitive).

Common situations: Typo in the option value (e.g. 'latency' lowercase instead of 'LATENCY'), copying an option from docs for an older Cassandra version, or tools generating DDL with stale option names.

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

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

Appendix: source

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

                {
                    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);
    }

    public static IndexWriterConfig emptyConfig()
    {
        return EMPTY_CONFIG;
    }

    @Override
    public String toString()
    {
        return String.format("IndexWriterConfig{%s=%d, %s=%d, %s=%s, %s=%s}",
                             MAXIMUM_NODE_CONNECTIONS, maximumNodeConnections,
                             CONSTRUCTION_BEAM_WIDTH, constructionBeamWidth,

View on GitHub (pinned to 88fd0f6a0e)