apache/cassandra · error · InvalidRequestException

Construction beam width for index %s cannot be <= 0 or > %s,

Error message

Construction beam width for index %s cannot be <= 0 or > %s, was %s

What it means

Thrown by IndexWriterConfig.fromOptions when 'construction_beam_width' parses to an integer outside the allowed range (must be > 0 and <= MAXIMUM_CONSTRUCTION_BEAM_WIDTH). It bounds the HNSW build-time candidate queue size to keep index builds tractable.

Source

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

                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
                {
                    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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Pick a positive value within MAXIMUM_CONSTRUCTION_BEAM_WIDTH (check the constant in IndexWriterConfig)
2. Omit the option to use the default beam width
3. Clamp the intended tuning value to the supported range in your tooling
4. Validate the range client-side before generating CQL

Example fix

// before
WITH OPTIONS = {'construction_beam_width': '0'}
// after
WITH OPTIONS = {'construction_beam_width': '120'}

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

try { session.execute(createIndexCql); }
catch (InvalidRequestException e) {
    if (e.getMessage().contains("Construction beam width for index") && e.getMessage().contains("cannot be <= 0 or >")) { /* clamp and retry */ }
    else throw e;
}

When it happens

Trigger: CREATE CUSTOM INDEX on a vector column WITH OPTIONS = {'construction_beam_width': '0'} or a negative value or one above MAXIMUM_CONSTRUCTION_BEAM_WIDTH (see IndexWriterConfig).

Common situations: Attempting to 'disable' beam search with 0; enormous widths copied from ANN tuning guides; swapping values with maximum_node_connections.

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

• Maximum number of connections for index %s cannot be <= 0 or
• Maximum node connections cannot be set without enabling %s
• Maximum number of connections %s is not a valid integer for
• Construction beam width cannot be set without enabling %s
• Construction beam width %s is not a valid integer for index

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