apache/cassandra · error · InvalidRequestException

Cosine similarity is not supported for single-dimension vect

Error message

Cosine similarity is not supported for single-dimension vectors

What it means

Cosine similarity is mathematically undefined for a 1-dimensional vector (norm-based angles do not apply). SAI's validateOptions rejects ANN indexes on vector<float,1> columns when the configured similarity function is COSINE, throwing VECTOR_1_DIMENSION_COSINE_ERROR.

Source

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

        {
            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));
    }

    @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Change the similarity function to EUCLIDEAN or DOT_PRODUCT in the index options.
2. If the data is truly multi-dimensional, fix the column's declared dimension to match the real embeddings.
3. Use a non-ANN index/query strategy if 1-dimensional similarity search is required.

Example fix

// before
WITH OPTIONS = {'similarity_function': 'COSINE'}  -- on vector<float, 1>
// after
WITH OPTIONS = {'similarity_function': 'EUCLIDEAN'}

if (vectorDimension === 1 && (options.similarity_function || 'COSINE') === 'COSINE') throw new Error('cosine is not valid for 1-d vectors; use EUCLIDEAN or DOT_PRODUCT');

catch (InvalidRequestException e) { if (e.getMessage().includes('single-dimension vectors')) { // retry with EUCLIDEAN similarity } }

When it happens

Trigger: CREATE CUSTOM INDEX on a vector<float, 1> column with OPTIONS {'similarity_function': 'COSINE'} (COSINE is also the default similarity in some paths, so even omitting the option can trigger it).

Common situations: Single-dimensional vector columns used as scalar embeddings; schema generated with dimension 1 by mistake; default similarity function left at COSINE.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• SAI ANN indexes are only allowed on vector columns with floa
• SAI ANN indexes are not allowed on multiple data directories
• Use of ANN OF in an ORDER BY clause requires a LIMIT that is
• QueryCancelledException(readCommand)
• Storage-attached index does not support the following IParti

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