apache/cassandra · error · InvalidRequestException

Maximum node connections cannot be set without enabling %s

Error message

Maximum node connections cannot be set without enabling %s

What it means

Thrown by IndexWriterConfig.fromOptions when option 'maximum_node_connections' is set for a vector index but the system property SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS is not enabled. Tuning this HNSW parameter is gated behind an experimental flag.

Source

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

    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));
            }
            if (options.containsKey(CONSTRUCTION_BEAM_WIDTH))
            {
                if (!CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS.getBoolean())
                    throw new InvalidRequestException(String.format("Construction beam width cannot be set without enabling %s", CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS.name()));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Enable the flag: add -Dcassandra.sai.vector.allow_custom_parameters=true to the JVM args (cassandra-env.sh) and restart
2. Remove maximum_node_connections from the index options and use defaults
3. Verify the exact property name for your Cassandra version (CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS)
4. Confirm the flag is set on every node in the cluster

Example fix

// before
WITH OPTIONS = {'maximum_node_connections': '32'}  // flag off
// after: JVM option
JVM_EXTRA_OPTS="$JVM_EXTRA_OPTS -Dcassandra.sai.vector.allow_custom_parameters=true"

if (opts.containsKey("maximum_node_connections") &&
    !Boolean.getBoolean("cassandra.sai.vector.allow_custom_parameters"))
    throw new IllegalStateException("Enable cassandra.sai.vector.allow_custom_parameters first");

try { session.execute(createIndexCql); }
catch (InvalidRequestException e) {
    if (e.getMessage().contains("Maximum node connections cannot be set without enabling")) { /* enable flag or drop option */ }
    else throw e;
}

When it happens

Trigger: CREATE CUSTOM INDEX on a vector column WITH OPTIONS = {'maximum_node_connections': '32'} without starting Cassandra with -Dcassandra.sai.vector.allow_custom_parameters=true (property name from CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS).

Common situations: Tuning HNSW graph connectivity on a cluster where the experimental flag was never set; flag set on a dev node but missing in production; flag renamed across Cassandra versions.

Related errors

• Construction beam width 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
• Construction beam width %s is not a valid integer for index
• Construction beam width for index %s cannot be <= 0 or > %s,

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