dotnet/efcore · error · InvalidOperationException

A vector index is defined for

Error message

A vector index is defined for `{entityType}.{property}`, but this property has not been configured as a vector. Use 'IsVectorProperty()' in 'OnModelCreating' to configure the property as a vector.

What it means

Thrown during model validation when an entity has a vector index whose single indexed property was not configured as a vector. CosmosModelValidator.ValidateVectorIndex checks that the property is an IProperty AND has both a vector distance function and vector dimensions set (the annotations applied by IsVectorProperty()). If any of those is missing the index is meaningless because Cosmos cannot build a vector index over a non-vector property.

Solutions

In OnModelCreating, call entityTypeBuilder.Property(p => p.Embedding).IsVectorProperty(distanceFunction, dimensions) on the property named in the error before/alongside HasVectorIndex.
Verify the property CLR type is a supported vector type (ReadOnlyMemory<float>, float[], ReadOnlyMemory<byte>, byte[], ReadOnlyMemory<sbyte>, sbyte[]).
Ensure dimensions is a positive int and distanceFunction is a valid Cosmos distance function string (e.g. 'cosine', 'dotproduct', 'euclidean').

Example fix

// before
modelBuilder.Entity<Doc>()
    .HasIndex(d => d.Embedding)              // ordinary index
    .HasVectorIndex();

// after
modelBuilder.Entity<Doc>(b =>
{
    b.Property(d => d.Embedding)
     .IsVectorProperty(DistanceFunction.Cosine, dimensions: 1536);
    b.HasIndex(d => d.Embedding)
     .HasVectorIndex();
});

Defensive patterns

Strategy: validation

Validate before calling

// Before UseCosmos / first query, assert the property is vector-configured.
var prop = modelBuilder.Model.FindEntityType(typeof(Doc))!
    .FindProperty(nameof(Doc.Embedding))!;
if (prop.GetVectorDistanceFunction() is null || prop.GetVectorDimensions() is null)
    throw new InvalidOperationException("Configure IsVectorProperty before HasVectorIndex.");

Prevention

Always pair HasVectorIndex with IsVectorProperty(distanceFunction, dimensions) in the same OnModelCreating block.
Add a model sanity-check unit test that iterates vector indexes and asserts their property has distance function + dimensions set.
Keep vector config centralized in one entity configuration class to avoid drift.

When it happens

Trigger: Calling HasVectorIndex on an entity for a property, but never calling IsVectorProperty(...) (with distance function + dimensions) on that same property in OnModelCreating. Also when an index is renamed/repurposed to a vector index while the property still holds a scalar mapping.

Common situations: Following a tutorial that shows HasVectorIndex but skips the IsVectorProperty call; copying vector config from another entity and forgetting the dimensions/distance-function arguments; upgrading EF Core Cosmos to a version that split vector index and vector property configuration.

Related errors

AI-assisted analysis of dotnet/efcore@3a2006ef56 (2026-08-11). Data as JSON: /api/errors/6e83b8ce08f047e5. Report an issue: GitHub.

Appendix: source

Thrown at src/EFCore.Cosmos/Infrastructure/Internal/CosmosModelValidator.cs:624

    protected virtual void ValidateVectorIndex(
        IIndex index,
        IDiagnosticsLogger<DbLoggerCategory.Model.Validation> logger)
    {
        var entityType = index.DeclaringEntityType;

        if (index.Properties.Count > 1)
        {
            throw new InvalidOperationException(
                CosmosStrings.CompositeVectorIndex(
                    entityType.DisplayName(),
                    string.Join(",", index.Properties.Select(e => e.Name))));
        }

        if (index.Properties[0] is not IProperty firstVectorIndexProperty
            || firstVectorIndexProperty.GetVectorDistanceFunction() == null
            || firstVectorIndexProperty.GetVectorDimensions() == null)
        {
            throw new InvalidOperationException(
                CosmosStrings.VectorIndexOnNonVector(
                    entityType.DisplayName(),
                    index.Properties[0].Name));
        }
    }

    /// <summary>
    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
    ///     any release. You should only use it directly in your code with extreme caution and knowing that
    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
    /// </summary>
    protected virtual void ValidateFullTextIndex(
        IIndex index,
        IDiagnosticsLogger<DbLoggerCategory.Model.Validation> logger)
    {
        if (index.Properties.Count > 1)
        {

View on GitHub (pinned to 3a2006ef56)