{"record":{"id":"98c9c4fa422a0695","repo":"apache/cassandra","slug":"construction-beam-width-for-index-s-cannot-be","errorCode":null,"errorMessage":"Construction beam width for index %s cannot be <= 0 or > %s, was %s","messagePattern":"Construction beam width 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":152,"sourceCode":"                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            }\n            if (options.containsKey(SIMILARITY_FUNCTION))\n            {\n                String option = toUpperCaseLocalized(options.get(SIMILARITY_FUNCTION));\n                try\n                {\n                    similarityFunction = VectorSimilarityFunction.valueOf(option);\n                }\n                catch (IllegalArgumentException e)\n                {\n                    throw new InvalidRequestException(String.format(\"Similarity function %s was not recognized for index %s. Valid values are: %s\",\n                                                                    option, indexName, validSimilarityFunctions));\n                }\n            }\n            if (options.containsKey(OPTIMIZE_FOR))\n            {\n                String option = toUpperCaseLocalized(options.get(OPTIMIZE_FOR));\n                try","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/disk/v1/IndexWriterConfig.java#L134-L170","documentation":"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.","triggerScenarios":"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).","commonSituations":"Attempting to 'disable' beam search with 0; enormous widths copied from ANN tuning guides; swapping values with maximum_node_connections.","solutions":["Pick a positive value within MAXIMUM_CONSTRUCTION_BEAM_WIDTH (check the constant in IndexWriterConfig)","Omit the option to use the default beam width","Clamp the intended tuning value to the supported range in your tooling","Validate the range client-side before generating CQL"],"exampleFix":"// before\nWITH OPTIONS = {'construction_beam_width': '0'}\n// after\nWITH OPTIONS = {'construction_beam_width': '120'}","handlingStrategy":"validation","validationCode":"int cbw = Integer.parseInt(opts.get(\"construction_beam_width\").trim());\nif (cbw <= 0 || cbw > MAXIMUM_CONSTRUCTION_BEAM_WIDTH /* see IndexWriterConfig */)\n    throw new IllegalArgumentException(\"construction_beam_width out of range: \" + cbw);","typeGuard":null,"tryCatchPattern":"try { session.execute(createIndexCql); }\ncatch (InvalidRequestException e) {\n    if (e.getMessage().contains(\"Construction beam width for index\") && e.getMessage().contains(\"cannot be <= 0 or >\")) { /* clamp and retry */ }\n    else throw e;\n}","preventionTips":["Clamp beam width to the supported maximum","Never use 0 or negative beam widths","Validate ranges against the constants of the Cassandra version in use"],"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"}