apache/cassandra · info · ClientWarn

ClientWarn.instance.warn(VECTOR_USAGE_WARNING)

Error message

ClientWarn.instance.warn(VECTOR_USAGE_WARNING)

What it means

This is a ClientWarn warning issued during CREATE INDEX option validation for a vector index: after validating the similarity function and dimensions, SAI warns the client that vector index support has constraints (e.g. limited when multiple data directories are configured — a hard error above — and other caveats surfaced in VECTOR_USAGE_WARNING). It is informational feedback returned to CQL clients, not an exception.

Solutions

1. Read the VECTOR_USAGE_WARNING text returned to the cqlsh/driver client and follow its guidance.
2. If planning multi-data-directory deployments, reconsider — multiple data_file_directories with vector indexes raises InvalidRequestException (VECTOR_MULTIPLE_DATA_DIRECTORY_ERROR).
3. Avoid COSINE similarity with 1-dimension vectors (rejected outright); pick dot_product or euclidean instead.
4. Pin to a Cassandra version where SAI vector indexes meet your production requirements.

// validate options before CREATE INDEX
// conf: data_file_directories must be a single directory for vector indexes
// dimension must be > 1 when using COSINE similarity

try { session.execute(createVectorIndexCql); } catch (InvalidRequestException e) { // handle VECTOR_MULTIPLE_DATA_DIRECTORY_ERROR / VECTOR_1_DIMENSION_COSINE_ERROR
 logger.warn(e.getMessage()); }

When it happens

Trigger: Executing CREATE CUSTOM INDEX ... USING 'StorageAttachedIndex' with a vector column and options that pass validation but merit a caution (dimension > 1, allowed similarity function), while the config passes the multiple-data-directory check.

Common situations: Creating vector search indexes in clusters spanning multiple data directories or on versions where SAI vector support is still restricted; developers evaluating ANN search on early Cassandra releases.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• ANN ordering by vector requires the column to be indexed
• CQL type cannot have vector options
• ANN ordering by vector requires all restricted column(s) to…
• Construction beam width cannot be set without enabling
• Construction beam width for index

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

Appendix: source

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

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