dotnet/efcore · error · InvalidOperationException

The 'VectorDistance' function can only be used with a…

Error message

The 'VectorDistance' function can only be used with a property mapped as a vector. Use 'IsVectorProperty()' in 'OnModelCreating' to configure the property as a vector.

What it means

CosmosVectorSearchTranslator throws VectorSearchRequiresVector when neither operand of EF.Functions.VectorDistance has a CosmosVectorTypeMapping. At least one operand must be a property configured as a vector so the provider can determine the element type, dimensions, and SQL shape. Without a vector mapping the call cannot be translated.

Solutions

1. Configure the vector property: modelBuilder.Entity<T>().Property(x => x.Embedding).IsVectorProperty(dimensions);
2. Ensure at least one operand of VectorDistance is the configured vector property (not a raw parameter on both sides).
3. Verify the property's column type is a vector type (e.g. Vector<float>) and the type mapping resolves to CosmosVectorTypeMapping.

Example fix

// before
modelBuilder.Entity<Item>().Property(x => x.Embedding);

// after
modelBuilder.Entity<Item>().Property(x => x.Embedding).IsVectorProperty(1536);

// At model build, assert the property used in VectorDistance is configured as a vector.
var prop = entityType.FindProperty(nameof(Item.Embedding));
if (prop?.GetVectorTypeMapping() is null)
    throw new InvalidOperationException($"{entityType.DisplayName()}.{nameof(Item.Embedding)} must be configured with IsVectorProperty.");

static bool IsVectorProperty(IProperty p) => p.GetTypeMapping() is CosmosVectorTypeMapping;

When it happens

Trigger: Calling EF.Functions.VectorDistance(a, b) where neither a nor b is a vector-typed property, e.g. passing two raw array parameters.

Common situations: Forgetting to call IsVectorProperty(dimension) in OnModelCreating for the property used in VectorDistance; passing two client-side arrays.

Related errors

• A vector index on ' ' is defined over properties ` `. A…
• Property ' . ' was configured for full-text search, but has…
• The type ' ' is being used as a vector, but the vector data…
• A full-text index on
• A vector index is defined for

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

Appendix: source

Thrown at src/EFCore.Cosmos/Query/Internal/Translators/CosmosVectorSearchTranslator.cs:59

        }

        if (useBruteForceExpression is not SqlConstantExpression { Value: var useBruteForceValue })
        {
            throw new InvalidOperationException(
                CoreStrings.ArgumentNotConstant("useBruteForce", nameof(CosmosDbFunctionsExtensions.VectorDistance)));
        }

        if (optionsExpression is not SqlConstantExpression { Value: var optionsValue })
        {
            throw new InvalidOperationException(
                CoreStrings.ArgumentNotConstant("options", nameof(CosmosDbFunctionsExtensions.VectorDistance)));
        }

        var options = (VectorDistanceOptions?)optionsValue;

        var vectorMapping = vector1.TypeMapping as CosmosVectorTypeMapping
            ?? vector2.TypeMapping as CosmosVectorTypeMapping
            ?? throw new InvalidOperationException(CosmosStrings.VectorSearchRequiresVector);

        var vectorType = vectorMapping.VectorType;

        List<Expression> newArguments =
        [
            sqlExpressionFactory.ApplyTypeMapping(vector1, vectorMapping), sqlExpressionFactory.ApplyTypeMapping(vector2, vectorMapping)
        ];

        if (useBruteForceValue is not null)
        {
            newArguments.Add(useBruteForceExpression);
        }

        if (options is not null)
        {
            // If the options are provided but not useBruteForce, we need to explicitly specify the default for the
            // latter (false)
            if (useBruteForceValue is null)

View on GitHub (pinned to 3a2006ef56)