{"record":{"id":"a3dbd9b5ddabd342","repo":"apache/cassandra","slug":"maximum-number-of-connections-for-index-s-cannot","errorCode":null,"errorMessage":"Maximum number of connections for index %s cannot be <= 0 or > %s, was %s","messagePattern":"Maximum number of connections for index (.+?) cannot be <= 0 or > (.+?), was (.+?)","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/disk/v1/IndexWriterConfig.java","lineNumber":135,"sourceCode":"            if (!indexTermType.isVector())\n                throw new InvalidRequestException(String.format(\"CQL type %s cannot have vector options\", indexTermType.asCQL3Type()));\n\n            if (options.containsKey(MAXIMUM_NODE_CONNECTIONS))\n            {\n                if (!CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS.getBoolean())\n                    throw new InvalidRequestException(String.format(\"Maximum node connections cannot be set without enabling %s\", CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS.name()));\n\n                try\n                {\n                    maximumNodeConnections = Integer.parseInt(options.get(MAXIMUM_NODE_CONNECTIONS));\n                }\n                catch (NumberFormatException e)\n                {\n                    throw new InvalidRequestException(String.format(\"Maximum number of connections %s is not a valid integer for index %s\",\n                                                                    options.get(MAXIMUM_NODE_CONNECTIONS), indexName));\n                }\n                if (maximumNodeConnections <= 0 || maximumNodeConnections > MAXIMUM_MAXIMUM_NODE_CONNECTIONS)\n                    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));\n            }\n            if (options.containsKey(CONSTRUCTION_BEAM_WIDTH))\n            {\n                if (!CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS.getBoolean())\n                    throw new InvalidRequestException(String.format(\"Construction beam width cannot be set without enabling %s\", CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS.name()));\n\n                try\n                {\n                    queueSize = Integer.parseInt(options.get(CONSTRUCTION_BEAM_WIDTH));\n                }\n                catch (NumberFormatException e)\n                {\n                    throw new InvalidRequestException(String.format(\"Construction beam width %s is not a valid integer for index %s\",\n                                                                    options.get(CONSTRUCTION_BEAM_WIDTH), indexName));\n                }\n                if (queueSize <= 0 || queueSize > MAXIMUM_CONSTRUCTION_BEAM_WIDTH)\n                    throw new InvalidRequestException(String.format(\"Construction beam width for index %s cannot be <= 0 or > %s, was %s\", indexName, MAXIMUM_CONSTRUCTION_BEAM_WIDTH, queueSize));\n            }","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/disk/v1/IndexWriterConfig.java#L117-L153","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\nWITH OPTIONS = {'maximum_node_connections': '0'}\n// after\nWITH OPTIONS = {'maximum_node_connections': '16'}","handlingStrategy":"validation","validationCode":"int mnc = Integer.parseInt(opts.get(\"maximum_node_connections\").trim());\nif (mnc <= 0 || mnc > MAXIMUM_MAXIMUM_NODE_CONNECTIONS /* see IndexWriterConfig */)\n    throw new IllegalArgumentException(\"maximum_node_connections out of range: \" + mnc);","typeGuard":null,"tryCatchPattern":"try { session.execute(createIndexCql); }\ncatch (InvalidRequestException e) {\n    if (e.getMessage().contains(\"cannot be <= 0 or >\")) { /* clamp value to range and retry */ }\n    else throw e;\n}","preventionTips":["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"],"tags":["cassandra","sai","vector-index","range-validation","index-options"],"backgroundTag":"value-out-of-range","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}