apache/cassandra · error · InvalidRequestException

CQL type %s cannot have vector options

Error message

CQL type %s cannot have vector options

What it means

Thrown by IndexWriterConfig.fromOptions when a SAI index on a non-vector column specifies vector-only options (maximum_node_connections, construction_beam_width, similarity_function, optimize_for). These options only make sense for vector (ANN) indexes, so Cassandra rejects the request.

Source

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

    public OptimizeFor getOptimizeFor()
    {
        return optimizeFor;
    }

    public static IndexWriterConfig fromOptions(String indexName, IndexTermType indexTermType, Map<String, String> options)
    {
        int maximumNodeConnections = DEFAULT_MAXIMUM_NODE_CONNECTIONS;
        int queueSize = DEFAULT_CONSTRUCTION_BEAM_WIDTH;
        VectorSimilarityFunction similarityFunction = DEFAULT_SIMILARITY_FUNCTION;
        OptimizeFor optimizeFor = DEFAULT_OPTIMIZE_FOR;

        if (options.get(MAXIMUM_NODE_CONNECTIONS) != null ||
            options.get(CONSTRUCTION_BEAM_WIDTH) != null ||
            options.get(SIMILARITY_FUNCTION) != null ||
            options.get(OPTIMIZE_FOR) != null)
        {
            if (!indexTermType.isVector())
                throw new InvalidRequestException(String.format("CQL type %s cannot have vector options", indexTermType.asCQL3Type()));

            if (options.containsKey(MAXIMUM_NODE_CONNECTIONS))
            {
                if (!CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS.getBoolean())
                    throw new InvalidRequestException(String.format("Maximum node connections cannot be set without enabling %s", CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS.name()));

                try
                {
                    maximumNodeConnections = Integer.parseInt(options.get(MAXIMUM_NODE_CONNECTIONS));
                }
                catch (NumberFormatException e)
                {
                    throw new InvalidRequestException(String.format("Maximum number of connections %s is not a valid integer for index %s",
                                                                    options.get(MAXIMUM_NODE_CONNECTIONS), indexName));
                }
                if (maximumNodeConnections <= 0 || maximumNodeConnections > MAXIMUM_MAXIMUM_NODE_CONNECTIONS)
                    throw new InvalidRequestException(String.format("Maximum number of connections for index %s cannot be <= 0 or > %s, was %s", indexName, MAXIMUM_MAXIMUM_NODE_CONNECTIONS, maximumNodeConnections));
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove the vector-only options from the non-vector index definition
2. Recreate the index on the actual vector column if ANN search was intended
3. Split the options map so scalar columns get their own options
4. Check the column type (vector<float, N>) before adding vector options

Example fix

// before
CREATE CUSTOM INDEX ON ks.tbl (name) USING 'StorageAttachedIndex'
  WITH OPTIONS = {'similarity_function': 'COSINE'};
// after
CREATE CUSTOM INDEX ON ks.tbl (name) USING 'StorageAttachedIndex';

Set<String> vectorOnly = Set.of("maximum_node_connections","construction_beam_width","similarity_function","optimize_for");
if (!columnType.startsWith("vector<") && opts.keySet().stream().anyMatch(vectorOnly::contains))
    throw new IllegalArgumentException("Vector-only options applied to non-vector column");

try { session.execute(createIndexCql); }
catch (InvalidRequestException e) {
    if (e.getMessage().contains("cannot have vector options")) { /* strip vector options or retarget index */ }
    else throw e;
}

When it happens

Trigger: CREATE CUSTOM INDEX on a scalar/text column USING 'StorageAttachedIndex' WITH OPTIONS containing any of similarity_function, maximum_node_connections, construction_beam_width, or optimize_for; indexTermType.isVector() is false.

Common situations: Copy-pasting a vector index definition and changing only the column; applying a shared WITH OPTIONS map to mixed-type columns; tooling that emits a uniform option set.

Related errors

• Empty value for boolean option ''
• Illegal value for boolean option '':
• Maximum node connections cannot be set without enabling %s
• Maximum number of connections %s is not a valid integer for
• Maximum number of connections for index %s cannot be <= 0 or

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