{"record":{"id":"497d75201940f538","repo":"dotnet/efcore","slug":"the-vectordistance-function-can-only-be-used-wit","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/EFCore.Cosmos/Query/Internal/Translators/CosmosVectorSearchTranslator.cs","lineNumber":59,"sourceCode":"        }\n\n        if (useBruteForceExpression is not SqlConstantExpression { Value: var useBruteForceValue })\n        {\n            throw new InvalidOperationException(\n                CoreStrings.ArgumentNotConstant(\"useBruteForce\", nameof(CosmosDbFunctionsExtensions.VectorDistance)));\n        }\n\n        if (optionsExpression is not SqlConstantExpression { Value: var optionsValue })\n        {\n            throw new InvalidOperationException(\n                CoreStrings.ArgumentNotConstant(\"options\", nameof(CosmosDbFunctionsExtensions.VectorDistance)));\n        }\n\n        var options = (VectorDistanceOptions?)optionsValue;\n\n        var vectorMapping = vector1.TypeMapping as CosmosVectorTypeMapping\n            ?? vector2.TypeMapping as CosmosVectorTypeMapping\n            ?? throw new InvalidOperationException(CosmosStrings.VectorSearchRequiresVector);\n\n        var vectorType = vectorMapping.VectorType;\n\n        List<Expression> newArguments =\n        [\n            sqlExpressionFactory.ApplyTypeMapping(vector1, vectorMapping), sqlExpressionFactory.ApplyTypeMapping(vector2, vectorMapping)\n        ];\n\n        if (useBruteForceValue is not null)\n        {\n            newArguments.Add(useBruteForceExpression);\n        }\n\n        if (options is not null)\n        {\n            // If the options are provided but not useBruteForce, we need to explicitly specify the default for the\n            // latter (false)\n            if (useBruteForceValue is null)","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/dotnet/efcore/blob/dbf9771522148d61a2467854921bd5dc6f6e6916/src/EFCore.Cosmos/Query/Internal/Translators/CosmosVectorSearchTranslator.cs#L41-L77","documentation":"EF.Functions.VectorDistance requires at least one of its two vector operands to be a property configured as a Cosmos vector (i.e., it carries a CosmosVectorTypeMapping). The translator at CosmosVectorSearchTranslator.cs:57-59 checks both operands' type mappings and throws if neither is a vector property. Without a vector mapping EF cannot determine the vector data type, dimensions, and distance function needed to generate valid SQL.","triggerScenarios":"Calling EF.Functions.VectorDistance(e.SomeProperty, queryVector, null, null) where 'SomeProperty' is not configured with IsVectorProperty() in OnModelCreating, or calling it with two runtime-supplied ReadOnlyMemory values and no mapped property on either side.","commonSituations":"Forgetting to call IsVectorProperty() on the embedding property in the model. Applying vector search on a property that has a value converter masking its type. Renaming the property but not updating the vector configuration.","solutions":["In OnModelCreating, configure the embedding property: modelBuilder.Entity<T>().Property(x => x.Embedding).IsVectorProperty(DistanceFunction.Cosine, /*dimensions*/ 1536, VectorDataType.Float32).","Ensure the property type is ReadOnlyMemory<float>, ReadOnlyMemory<byte>, or ReadOnlyMemory<sbyte> so EF can assign the CosmosVectorTypeMapping.","Verify the VectorDistance call references the mapped property (e.g., e.Embedding) on at least one side."],"exampleFix":"// before\nmodelBuilder.Entity<Document>().Property(d => d.Embedding); // not configured as vector\n\n// after\nmodelBuilder.Entity<Document>()\n    .Property(d => d.Embedding)\n    .IsVectorProperty(DistanceFunction.Cosine, dimensions: 1536, VectorDataType.Float32);","handlingStrategy":"validation","validationCode":"// After building the model, verify the embedding property has a vector type mapping.\nvar model = context.Model.FindEntityType(typeof(Document))!;\nvar embedding = model.GetProperties().First(p => p.Name == nameof(Document.Embedding));\nvar mapping = embedding.FindTypeMapping();\nif (mapping is not CosmosVectorTypeMapping)\n    throw new InvalidOperationException(\"Embedding property is not configured as a vector.\");","typeGuard":"// Type guard to confirm a property is vector-mapped before querying\nstatic bool IsVectorProperty(IProperty property)\n    => property.FindTypeMapping() is CosmosVectorTypeMapping;","tryCatchPattern":null,"preventionTips":["Always call IsVectorProperty() with dimensions and distance function in OnModelCreating for embedding properties.","Ensure the CLR type is ReadOnlyMemory<float> (or byte/sbyte) so the vector mapping is assigned.","Write a model-validation test asserting the embedding property has a CosmosVectorTypeMapping."],"tags":["cosmos","vector-search","model-configuration","query-translation"],"analyzedSha":"dbf9771522148d61a2467854921bd5dc6f6e6916","analyzedAt":"2026-08-06T20:46:03.226Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}