What causes "Maximum number of connections for index %s cannot be %s, was %s" in apache/cassandra?

Choose a positive value within the allowed maximum (check MAXIMUM_MAXIMUM_NODE_CONNECTIONS in IndexWriterConfig)

apache/cassandra · error · InvalidRequestException

Maximum number of connections for index %s cannot be <= 0 or

Error message

Maximum number of connections for index %s cannot be <= 0 or > %s, was %s

What it means

Thrown by IndexWriterConfig.fromOptions when 'maximum_node_connections' parses to an integer outside the allowed range (must be > 0 and <= MAXIMUM_MAXIMUM_NODE_CONNECTIONS). The value controls HNSW graph connectivity and is bounded to protect memory and build performance.

Source

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

            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()));

                try
                {
                    queueSize = Integer.parseInt(options.get(CONSTRUCTION_BEAM_WIDTH));
                }
                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));
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Choose a positive value within the allowed maximum (check MAXIMUM_MAXIMUM_NODE_CONNECTIONS in IndexWriterConfig)
Use the default by removing the option entirely
Re-check the intended HNSW M parameter and clamp it to the supported range
Validate the range client-side before generating the options map

Example fix

// before
WITH OPTIONS = {'maximum_node_connections': '0'}
// after
WITH OPTIONS = {'maximum_node_connections': '16'}

Defensive patterns

Strategy: validation

Validate before calling

int mnc = Integer.parseInt(opts.get("maximum_node_connections").trim());
if (mnc <= 0 || mnc > MAXIMUM_MAXIMUM_NODE_CONNECTIONS /* see IndexWriterConfig */)
    throw new IllegalArgumentException("maximum_node_connections out of range: " + mnc);

Try / catch

try { session.execute(createIndexCql); }
catch (InvalidRequestException e) {
    if (e.getMessage().contains("cannot be <= 0 or >")) { /* clamp value to range and retry */ }
    else throw e;
}

Prevention

Clamp tuning values to the documented range before use
Never pass 0 or negatives for graph parameters
Read MAXIMUM_MAXIMUM_NODE_CONNECTIONS from the matching Cassandra version, not docs for another version

When it happens

Trigger: CREATE CUSTOM INDEX on a vector column WITH OPTIONS = {'maximum_node_connections': '0'}, a negative value, or a value exceeding MAXIMUM_MAXIMUM_NODE_CONNECTIONS (see IndexWriterConfig constant).

Common situations: Trying to disable graph connections with 0; extreme tuning values copied from blog posts; confusing this option with construction_beam_width and swapping their magnitudes.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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