apache/cassandra · error · InvalidRequestException

Maximum number of connections %s is not a valid integer for

Error message

Maximum number of connections %s is not a valid integer for index %s

What it means

Thrown by IndexWriterConfig.fromOptions when the value of 'maximum_node_connections' cannot be parsed as an integer. The option must be a plain integer string; anything else (letters, decimals, whitespace-only) fails Integer.parseInt.

Source

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

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

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Provide a plain integer string, e.g. 'maximum_node_connections': '32'
2. Remove any decimal point, units, or non-digit characters
3. Trim whitespace from the value
4. Validate with Integer.parseInt (or a regex ^-?\d+$) before issuing the CQL

Example fix

// before
WITH OPTIONS = {'maximum_node_connections': '32.0'}
// after
WITH OPTIONS = {'maximum_node_connections': '32'}

String v = opts.get("maximum_node_connections");
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("is not a valid integer")) { /* coerce/fix the option value */ }
    else throw e;
}

When it happens

Trigger: CREATE CUSTOM INDEX on a vector column WITH OPTIONS = {'maximum_node_connections': 'thirty-two'} or '32.0' or ' 32' (unparseable by Integer.parseInt).

Common situations: Quoting/decimal mistakes; passing a float-formatted number; locale or whitespace artifacts from generated CQL; user thinking the value is a percentage.

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

• Construction beam width %s is not a valid integer for index
• 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/8dce1c1abb199a57. Report an issue: GitHub.