apache/cassandra · error · InvalidRequestException

SAI ANN indexes are not allowed on multiple data directories

Error message

SAI ANN indexes are not allowed on multiple data directories

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java:310

                if (!SUPPORTED_TYPES.contains(subType.asCQL3Type()) && !subType.isFrozen())
                    throw new InvalidRequestException("Unsupported type: " + subType.asCQL3Type());
            }
        }
        else if (!SUPPORTED_TYPES.contains(indexTermType.asCQL3Type()) && !indexTermType.isFrozen())
        {
            throw new InvalidRequestException("Unsupported type: " + indexTermType.asCQL3Type());
        }
        // If this is a vector type we need to validate it for the current vector index constraints
        else if (indexTermType.isVector())
        {
            if (!(indexTermType.vectorElementType() instanceof FloatType))
                throw new InvalidRequestException(VECTOR_NON_FLOAT_ERROR);

            if (indexTermType.vectorDimension() == 1 && config.getSimilarityFunction() == VectorSimilarityFunction.COSINE)
                throw new InvalidRequestException(VECTOR_1_DIMENSION_COSINE_ERROR);

            if (DatabaseDescriptor.getRawConfig().data_file_directories.length > 1)
                throw new InvalidRequestException(VECTOR_MULTIPLE_DATA_DIRECTORY_ERROR);

            ClientWarn.instance.warn(VECTOR_USAGE_WARNING);
        }

        return Collections.emptyMap();
    }

    @Override
    public void register(IndexRegistry registry)
    {
        // index will be available for writes
        registry.registerIndex(this, StorageAttachedIndexGroup.GROUP_KEY, () -> new StorageAttachedIndexGroup(baseCfs));
    }

    @Override
    public void unregister(IndexRegistry registry)
    {
        registry.unregisterIndex(this, StorageAttachedIndexGroup.GROUP_KEY);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Configure a single data_file_directories entry for nodes hosting vector indexes (and restart).
2. Move vector tables to a cluster/nodes with a single data directory.
3. Use non-ANN retrieval (e.g., exact filtering without the vector index) until the node is reconfigured.
4. Check for newer Cassandra versions where this restriction may be lifted.

Example fix

// before (cassandra.yaml)
data_file_directories:
  - /data1
  - /data2
// after
data_file_directories:
  - /data1

String[] dirs = DatabaseDescriptor.getRawConfig().data_file_directories; if (dirs != null && dirs.length > 1) throw new IllegalStateException('vector ANN indexes require a single data directory');

catch (InvalidRequestException e) { if (e.getMessage().includes('not allowed on multiple data directories')) { // reconfigure cassandra.yaml to one data dir or relocate vector workloads } }

When it happens

Trigger: Creating an SAI ANN index on a vector column on a node whose cassandra.yaml data_file_directories lists 2+ directories.

Common situations: Multi-disk nodes using JBOD configurations attempting vector workloads; environments where vector indexes were enabled before the multi-directory restriction was known.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• SAI ANN indexes are only allowed on vector columns with floa
• Cosine similarity is not supported for single-dimension vect
• Use of ANN OF in an ORDER BY clause requires a LIMIT that is
• Load CIDR groups cache operation not supported by %s
• Unsupported parameter '%s' for %s, supported parameters are

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/ad4b736f425d8ae7. Report an issue: GitHub.