{"record":{"id":"bdade9edb89a25a0","repo":"apache/cassandra","slug":"construction-beam-width-cannot-be-set-without-enab","errorCode":null,"errorMessage":"Construction beam width cannot be set without enabling %s","messagePattern":"Construction beam width cannot be set without enabling (.+?)","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/disk/v1/IndexWriterConfig.java","lineNumber":140,"sourceCode":"                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            }\n            if (options.containsKey(SIMILARITY_FUNCTION))\n            {\n                String option = toUpperCaseLocalized(options.get(SIMILARITY_FUNCTION));\n                try\n                {","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/disk/v1/IndexWriterConfig.java#L122-L158","documentation":"Thrown by IndexWriterConfig.fromOptions when option 'construction_beam_width' is set for a vector index but the system property SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS is not enabled. Like maximum_node_connections, tuning this build-time parameter is gated behind an experimental flag.","triggerScenarios":"CREATE CUSTOM INDEX on a vector column WITH OPTIONS = {'construction_beam_width': '200'} without -Dcassandra.sai.vector.allow_custom_parameters=true set on the node.","commonSituations":"Tuning build throughput/memory tradeoff on a cluster lacking the experimental flag; flag enabled locally but not on the target environment; upgrading to a version that added the gate.","solutions":["Enable -Dcassandra.sai.vector.allow_custom_parameters=true in cassandra-env.sh and restart","Remove construction_beam_width from the options and rely on defaults","Gate the option in your schema-management tooling on the flag being set","Ensure the flag is enabled cluster-wide before running the DDL"],"exampleFix":"// before\nWITH OPTIONS = {'construction_beam_width': '200'}  // flag off\n// after: JVM option\nJVM_EXTRA_OPTS=\"$JVM_EXTRA_OPTS -Dcassandra.sai.vector.allow_custom_parameters=true\"","handlingStrategy":"validation","validationCode":"if (opts.containsKey(\"construction_beam_width\") &&\n    !Boolean.getBoolean(\"cassandra.sai.vector.allow_custom_parameters\"))\n    throw new IllegalStateException(\"Enable cassandra.sai.vector.allow_custom_parameters first\");","typeGuard":null,"tryCatchPattern":"try { session.execute(createIndexCql); }\ncatch (InvalidRequestException e) {\n    if (e.getMessage().contains(\"Construction beam width cannot be set without enabling\")) { /* enable flag or drop option */ }\n    else throw e;\n}","preventionTips":["Gate both construction_beam_width and maximum_node_connections behind the same flag check","Confirm the experimental flag is set cluster-wide","Default to built-in beam width unless tuning is explicitly needed"],"tags":["cassandra","sai","vector-index","feature-flag","index-options"],"backgroundTag":"feature-not-enabled","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"}