apache/cassandra · error · InvalidRequestException

Construction beam width cannot be set without enabling %s

Error message

Construction beam width cannot be set without enabling %s

What it means

Thrown by IndexWriterConfig.fromOptions when option 'construction_beam_width' is set for a vector index but the system property SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS is not enabled. Like maximum_node_connections, tuning this build-time parameter is gated behind an experimental flag.

Source

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

                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));
            }
            if (options.containsKey(SIMILARITY_FUNCTION))
            {
                String option = toUpperCaseLocalized(options.get(SIMILARITY_FUNCTION));
                try
                {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Enable -Dcassandra.sai.vector.allow_custom_parameters=true in cassandra-env.sh and restart
2. Remove construction_beam_width from the options and rely on defaults
3. Gate the option in your schema-management tooling on the flag being set
4. Ensure the flag is enabled cluster-wide before running the DDL

Example fix

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

if (opts.containsKey("construction_beam_width") &&
    !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("Construction beam width 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 = {'construction_beam_width': '200'} without -Dcassandra.sai.vector.allow_custom_parameters=true set on the node.

Common situations: Tuning build throughput/memory tradeoff on a cluster lacking the experimental flag; flag enabled locally but not on the target environment; upgrading to a version that added the gate.

Related errors

• 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
• 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/bdade9edb89a25a0. Report an issue: GitHub.