apache/cassandra · error · InvalidRequestException

SAI ANN indexes are only allowed on vector columns with floa

Error message

SAI ANN indexes are only allowed on vector columns with float elements

What it means

SAI vector (ANN) indexes require the vector's element type to be float. When validateOptions sees a vector target whose vectorElementType() is not FloatType, it throws VECTOR_NON_FLOAT_ERROR ('SAI ANN indexes are only allowed on vector columns with float elements').

Source

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

        // If we are indexing map entries we need to validate the subtypes
        if (indexTermType.isComposite())
        {
            for (IndexTermType subType : indexTermType.subTypes())
            {
                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));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Declare the column as vector<float, N> (float elements) and re-create the index.
Migrate existing data: add a float-typed vector column, copy/convert values, then index it.
Drop and re-create the table with the correct vector type if data volume is small.

Example fix

// before
embedding vector<int, 128>
// after
ALTER TABLE ks.tbl ADD embedding_f vector<float, 128>;
CREATE CUSTOM INDEX ON ks.tbl (embedding_f) USING 'StorageAttachedIndex';

Defensive patterns

Strategy: validation

Validate before calling

const m = /^vector<\s*([a-z]+)\s*,\s*(\d+)\s*>$/.exec(columnType); if (!m || m[1] !== 'float') throw new Error('vector columns must use float elements for SAI ANN');

Type guard

function isFloatVector(cqlType) { const m = /^vector<\s*float\s*,\s*\d+\s*>$/.exec(cqlType); return m !== null; }

Try / catch

catch (InvalidRequestException e) { if (e.getMessage().includes('only allowed on vector columns with float elements')) { // migrate column to vector<float,N> and recreate index } }

Prevention

Always declare embedding columns as vector<float, N>
Add schema linting to reject non-float vectors for ANN
Standardize embedding pipeline output to float32

When it happens

Trigger: CREATE CUSTOM INDEX ... USING 'StorageAttachedIndex' with function ANN/option on a vector column declared with a non-float element type (e.g., vector<int, N> or vector<double, N>).

Common situations: Creating vector columns with integer embeddings; copying vector schema from other systems using double precision; typo in the vector type declaration.

Related errors

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