{"record":{"id":"ad4b736f425d8ae7","repo":"apache/cassandra","slug":"sai-ann-indexes-are-not-allowed-on-multiple-data-d","errorCode":null,"errorMessage":"SAI ANN indexes are not allowed on multiple data directories","messagePattern":"SAI ANN indexes are not allowed on multiple data directories","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java","lineNumber":310,"sourceCode":"                if (!SUPPORTED_TYPES.contains(subType.asCQL3Type()) && !subType.isFrozen())\n                    throw new InvalidRequestException(\"Unsupported type: \" + subType.asCQL3Type());\n            }\n        }\n        else if (!SUPPORTED_TYPES.contains(indexTermType.asCQL3Type()) && !indexTermType.isFrozen())\n        {\n            throw new InvalidRequestException(\"Unsupported type: \" + indexTermType.asCQL3Type());\n        }\n        // If this is a vector type we need to validate it for the current vector index constraints\n        else if (indexTermType.isVector())\n        {\n            if (!(indexTermType.vectorElementType() instanceof FloatType))\n                throw new InvalidRequestException(VECTOR_NON_FLOAT_ERROR);\n\n            if (indexTermType.vectorDimension() == 1 && config.getSimilarityFunction() == VectorSimilarityFunction.COSINE)\n                throw new InvalidRequestException(VECTOR_1_DIMENSION_COSINE_ERROR);\n\n            if (DatabaseDescriptor.getRawConfig().data_file_directories.length > 1)\n                throw new InvalidRequestException(VECTOR_MULTIPLE_DATA_DIRECTORY_ERROR);\n\n            ClientWarn.instance.warn(VECTOR_USAGE_WARNING);\n        }\n\n        return Collections.emptyMap();\n    }\n\n    @Override\n    public void register(IndexRegistry registry)\n    {\n        // index will be available for writes\n        registry.registerIndex(this, StorageAttachedIndexGroup.GROUP_KEY, () -> new StorageAttachedIndexGroup(baseCfs));\n    }\n\n    @Override\n    public void unregister(IndexRegistry registry)\n    {\n        registry.unregisterIndex(this, StorageAttachedIndexGroup.GROUP_KEY);","sourceCodeStart":292,"sourceCodeEnd":328,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java#L292-L328","documentation":"SAI ANN (vector) indexes currently require all vector data to live under a single data directory. validateOptions checks DatabaseDescriptor's data_file_directories and, if more than one is configured, throws VECTOR_MULTIPLE_DATA_DIRECTORY_ERROR.","triggerScenarios":"Creating an SAI ANN index on a vector column on a node whose cassandra.yaml data_file_directories lists 2+ directories.","commonSituations":"Multi-disk nodes using JBOD configurations attempting vector workloads; environments where vector indexes were enabled before the multi-directory restriction was known.","solutions":["Configure a single data_file_directories entry for nodes hosting vector indexes (and restart).","Move vector tables to a cluster/nodes with a single data directory.","Use non-ANN retrieval (e.g., exact filtering without the vector index) until the node is reconfigured.","Check for newer Cassandra versions where this restriction may be lifted."],"exampleFix":"// before (cassandra.yaml)\ndata_file_directories:\n  - /data1\n  - /data2\n// after\ndata_file_directories:\n  - /data1","handlingStrategy":"validation","validationCode":"String[] dirs = DatabaseDescriptor.getRawConfig().data_file_directories; if (dirs != null && dirs.length > 1) throw new IllegalStateException('vector ANN indexes require a single data directory');","typeGuard":null,"tryCatchPattern":"catch (InvalidRequestException e) { if (e.getMessage().includes('not allowed on multiple data directories')) { // reconfigure cassandra.yaml to one data dir or relocate vector workloads } }","preventionTips":["Pin vector workloads to single-data-directory nodes","Audit cassandra.yaml data_file_directories before enabling SAI vectors","Document the JBOD/ANN incompatibility in cluster runbooks"],"tags":["cassandra","sai","vector","configuration"],"backgroundTag":"invalid-config-value","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"}