{"record":{"id":"e1d864f4f57d959f","repo":"apache/cassandra","slug":"maximum-node-connections-cannot-be-set-without-ena","errorCode":null,"errorMessage":"Maximum node connections cannot be set without enabling %s","messagePattern":"Maximum node connections 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":123,"sourceCode":"    public static IndexWriterConfig fromOptions(String indexName, IndexTermType indexTermType, Map<String, String> options)\n    {\n        int maximumNodeConnections = DEFAULT_MAXIMUM_NODE_CONNECTIONS;\n        int queueSize = DEFAULT_CONSTRUCTION_BEAM_WIDTH;\n        VectorSimilarityFunction similarityFunction = DEFAULT_SIMILARITY_FUNCTION;\n        OptimizeFor optimizeFor = DEFAULT_OPTIMIZE_FOR;\n\n        if (options.get(MAXIMUM_NODE_CONNECTIONS) != null ||\n            options.get(CONSTRUCTION_BEAM_WIDTH) != null ||\n            options.get(SIMILARITY_FUNCTION) != null ||\n            options.get(OPTIMIZE_FOR) != null)\n        {\n            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","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/disk/v1/IndexWriterConfig.java#L105-L141","documentation":"Thrown by IndexWriterConfig.fromOptions when option 'maximum_node_connections' is set for a vector index but the system property SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS is not enabled. Tuning this HNSW parameter is gated behind an experimental flag.","triggerScenarios":"CREATE CUSTOM INDEX on a vector column WITH OPTIONS = {'maximum_node_connections': '32'} without starting Cassandra with -Dcassandra.sai.vector.allow_custom_parameters=true (property name from CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS).","commonSituations":"Tuning HNSW graph connectivity on a cluster where the experimental flag was never set; flag set on a dev node but missing in production; flag renamed across Cassandra versions.","solutions":["Enable the flag: add -Dcassandra.sai.vector.allow_custom_parameters=true to the JVM args (cassandra-env.sh) and restart","Remove maximum_node_connections from the index options and use defaults","Verify the exact property name for your Cassandra version (CassandraRelevantProperties.SAI_VECTOR_ALLOW_CUSTOM_PARAMETERS)","Confirm the flag is set on every node in the cluster"],"exampleFix":"// before\nWITH OPTIONS = {'maximum_node_connections': '32'}  // 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(\"maximum_node_connections\") &&\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(\"Maximum node connections cannot be set without enabling\")) { /* enable flag or drop option */ }\n    else throw e;\n}","preventionTips":["Treat custom vector parameters as experimental and document the required flag","Verify the flag in cassandra-env.sh on all nodes before DDL","Fall back to default HNSW parameters unless the flag is enabled"],"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"}