apache/cassandra · error · InvalidRequestException

Construction beam width %s is not a valid integer for index

Error message

Construction beam width %s is not a valid integer for index %s

What it means

Fired in SAI IndexWriterConfig.fromOptions while parsing index CREATE/OPTIONS: the 'beam_width' option string cannot be parsed as an integer (NumberFormatException caught and rethrown as InvalidRequestException). This is a config-value validation guard for vector-index ANN search tuning, naming the bad value and the index.

Source

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

                {
                    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
                {
                    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));
                }
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Provide a plain integer string, e.g. 'construction_beam_width': '120'
2. Remove decimals, units, or stray characters
3. Trim whitespace around the value
4. Validate with Integer.parseInt before submitting the DDL

Example fix

// before
WITH OPTIONS = {'construction_beam_width': '200.5'}
// after
WITH OPTIONS = {'construction_beam_width': '200'}

String v = opts.get("construction_beam_width");
if (v != null) Integer.parseInt(v.trim()); // throws NumberFormatException before the DDL if invalid

try { session.execute(createIndexCql); }
catch (InvalidRequestException e) {
    if (e.getMessage().contains("Construction beam width") && e.getMessage().contains("not a valid integer")) { /* fix value */ }
    else throw e;
}

When it happens

Trigger: CREATE CUSTOM INDEX on a vector column WITH OPTIONS = {'construction_beam_width': 'wide'} or '200.5' or ' 200' — any non-integer string.

Common situations: Decimal or unit-suffixed values; whitespace from template interpolation; typos in generated CQL; confusion with memory-size strings like '200M'.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Maximum number of connections %s is not a valid integer for
• Maximum node connections cannot be set without enabling %s
• Maximum number of connections for index %s cannot be <= 0 or
• Construction beam width cannot be set without enabling %s
• 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/a5f8e4b3e6101ff8. Report an issue: GitHub.